Wiki Structure

The compiled wiki is a directory of plain markdown files — an index, topic articles, concept articles, and a schema — all readable in Obsidian.

Output Directory Layout

After running /wiki-compile, your configured output directory contains:

wiki/
├── INDEX.md          ← entry point, lists all topics and concepts
├── schema.md         ← naming conventions, topic list, cross-reference rules
├── compile-log.md    ← record of what changed in each compilation run
├── topics/
│   ├── retention.md
│   ├── onboarding.md
│   └── ...           ← one file per topic
└── concepts/
    ├── speed-vs-quality-tradeoff.md
    └── ...           ← one file per cross-cutting pattern

All files are plain markdown with Obsidian-style [[wikilinks]]. Open wiki/INDEX.md in Obsidian and you’ll see the full knowledge base with bidirectional links to source files. Set "link_style": "markdown" in .wiki-compiler.json if you prefer standard links.

INDEX.md — The Entry Point

INDEX.md is the file your agent reads first at session startup. It lists every topic and concept with source counts, last-updated dates, and status, so Claude knows at a glance what the wiki covers and which articles to read for the current task.

# My Project Knowledge Base

Last compiled: 2026-04-07
Total topics: 12 | Total concepts: 3 | Total sources: 383

## Topics

| Topic                    | Sources | Last Updated | Status |
|--------------------------|---------|-------------|--------|
| [[topics/retention]]     | 47      | 2026-04-06  | active |
| [[topics/onboarding]]    | 23      | 2026-04-05  | active |

## Concepts

| Concept                                   | Topics Connected              | Last Updated |
|-------------------------------------------|-------------------------------|-------------|
| [[concepts/speed-vs-quality-tradeoff]]    | retention, push, experiments  | 2026-04-06  |

## Recent Changes
- 2026-04-07: Recompiled retention (4 new sources), added concept speed-vs-quality-tradeoff

Topic Articles

Each topic article covers everything known about one subject, synthesized from all contributing source files. Topic files live in topics/ and use lowercase-kebab-case filenames (e.g., topics/d1-retention.md).

The frontmatter records compilation metadata:

---
topic: Retention
last_compiled: 2026-04-07
source_count: 47
status: active
---

Every section in the article carries a coverage indicator so you and your agent know how well-sourced each part is:

## Summary [coverage: high -- 15 sources]
Standalone briefing of the topic. Someone reading only this section
should understand the current state without opening any source file.

## Timeline [coverage: high -- 12 sources]
- **2026-01-14:** Launched D1 push notification experiment
- **2026-02-28:** Experiment concluded, +4.2pp D1 lift confirmed

## Current State [coverage: medium -- 4 sources]
What is true right now: active metrics, live experiments, open questions.

## Key Decisions [coverage: medium -- 3 sources]
- **2026-03-01:** Chose to ship push as default-on -- outweighed opt-out concerns

## Sources
- [[../../meetings/2026-01-14-retention-sync]]
- [[../../strategy/retention-strategy-2026]]

The Sources section at the bottom of every article lists backlinks to every raw file that contributed — so you can always trace synthesized claims back to their origins.

The default article structure (Summary, Timeline, Current State, Key Decisions, Experiments & Results, Gotchas, Open Questions, Sources) is a starting point. During /wiki-init, the compiler proposes a structure tailored to your domain. You can edit article_sections in .wiki-compiler.json at any time.

Concept Articles

Concept articles live in concepts/ and capture patterns that span three or more topics. They are interpretive — they answer “what does this pattern mean across the project?” rather than just recording what happened in each topic.

The compiler discovers concepts automatically after each full compile. You can also seed them in schema.md if you know what patterns you want tracked.

Example concept article excerpt

---
concept: Speed vs Quality Tradeoff
last_compiled: 2026-04-07
topics: [retention, push-notifications, experiment-design]
instances: 6
---

# Speed vs Quality Tradeoff

## Pattern Summary [coverage: high -- 18 sources]
Across 6 decision points in Q1 2026, the team repeatedly chose faster
iteration over more rigorous measurement. This pattern appears in retention
experiments (abbreviated holdout windows), push notification rollout
(shipped before full segmentation analysis), and experiment design
(reduced significance thresholds to hit roadmap dates).

## Instances [coverage: high -- 18 sources]
- **Retention / D1 experiment:** ...
- **Push notifications / rollout:** ...

## Implications [coverage: medium -- 4 sources]
...

## Sources
- [[../topics/retention]]
- [[../topics/push-notifications]]
- [[../topics/experiment-design]]

schema.md — The Wiki’s Constitution

schema.md is generated on first compile and defines the rules the compiler follows on every subsequent run. It covers:

• Topics — every topic slug and a one-line description of what it covers
• Concepts — cross-cutting patterns and the topics they connect
• Article structure — section names, order, and coverage tag format
• Naming conventions — slug format (lowercase-kebab-case), date format (YYYY-MM-DD), link style
• Cross-reference rules — topics that share 3+ sources should reference each other
• Evolution log — a chronological record of every schema change

You can edit schema.md directly. Rename a topic slug, merge two topics, or add a convention — the compiler reads it before each run and applies your changes. New topics discovered during compilation are added automatically with a log entry.

## Topics
- retention: D1/D7/D30 retention metrics, experiments, and strategy
- onboarding: New user activation flow and first-session experience

## Concepts
- speed-vs-quality-tradeoff: recurring decision pattern — connects [retention, push-notifications, experiment-design]

## Naming Conventions
- Topic slugs: lowercase-kebab-case
- Files: {topic-slug}.md in topics/
- Dates: YYYY-MM-DD format everywhere
- Links: Obsidian [[wikilinks]] with relative paths from topics/

## Cross-Reference Rules
- Topics sharing 3+ sources should reference each other in Summary or Key Decisions
- When a gotcha applies to multiple topics, include it in each with a note like "(also in [[other-topic]])"

## Evolution Log
- 2026-04-01: Initial schema generated from 383 source files
- 2026-04-07: Added concept speed-vs-quality-tradeoff

Don’t delete topics from schema.md without also removing the corresponding file from topics/. Run /wiki-lint after schema edits to catch any drift between the schema and the actual wiki files.