wiki · diff

git:20260406.c5a3532 to git:20260503.631b94d

40 added, 261 removed. Audit A to A.

---

name: wiki

description: >-

Markdown-first knowledge base where the LLM acts as librarian. Ingests raw

sources, compiles and interlinks topic files, self-maintains an index. No

vector DB or embeddings required -- uses LLM-native navigation over structured

markdown up to ~400K words.

user-invocable: true

auto-trigger: false

trigger_keywords:

- wiki

- knowledge base

- llm wiki

- project wiki

- build a wiki

- maintain knowledge

- knowledge management

- llm-wiki

- karpathy wiki

last-updated: 2026-04-06

---

# /wiki -- LLM-Native Knowledge Base

- ## Identity

- You are a librarian. You maintain a structured markdown knowledge base for a

- project -- ingesting raw sources, compiling them into interlinked topic files,

- and maintaining a navigable index. You answer questions by reasoning over the

- index and reading relevant topics, not by embedding search.

- Inspired by Andrej Karpathy's `llm-wiki` pattern: the LLM reads, writes, and

- navigates the wiki directly. No vector database. No embeddings. Just markdown

- files and the LLM's own reasoning.

## Orientation

- **Use when:**

- - Building or maintaining a project knowledge base

- - Ingesting documentation, research, meeting notes, or raw text into structured topics

- - Answering questions about a project's accumulated knowledge

- - Compacting or reorganizing scattered information into a navigable structure

- **Do NOT use when:**

- - The knowledge base exceeds ~400K words (consider chunked retrieval instead)

- - Real-time data is needed (this is a static knowledge store, not a live feed)

- - The question can be answered by reading one file directly (just read it)

+ **Use when:** building and querying a markdown-first knowledge base -- ingests raw notes, deduplicates, surfaces answers.

+ **Don't use when:** capturing session learnings into the evolve pipeline (use /learn); generating structured code documentation (use /doc-gen).

## Directory Structure

- The wiki lives in a `wiki/` directory at the project root (or a user-specified

- location):

```text

wiki/

- index.md # Master index: topic list with summaries and cross-links

- raw/ # Intake directory for unprocessed sources

- source-001.md # Raw ingested content (URLs, files, pasted text)

- source-002.md # Each source gets a timestamped file

- topics/ # Compiled topic files

- topic-slug.md # One file per topic, interlinked

- another-topic.md

- .wiki-meta.json # Wiki metadata: stats, last compaction, source count

+ index.md # Master index

+ raw/ # Unprocessed sources (timestamped files)

+ topics/ # Compiled topic files (one per topic, interlinked)

+ .wiki-meta.json # Stats: topic count, source count, last compaction

```

## Commands

| Command | Behavior |

|---|---|

| `/wiki` | Status overview: topic count, last update, pending raw sources |

| `/wiki --add [source]` | Ingest a new source into the wiki |

| `/wiki --query [question]` | Answer a question using wiki knowledge |

| `/wiki --status` | Detailed wiki health: topic count, staleness, orphan detection |

| `/wiki --compact` | Merge, deduplicate, and reorganize topics |

| `/wiki --rebuild-index` | Regenerate index.md from current topic files |

| `/wiki init [path]` | Initialize a new wiki at the specified path |

## Protocol

### Command: `/wiki init [path]`

- Initialize a new wiki directory.

- 1. Determine the wiki path: use the argument, or default to `wiki/` at project root

- 2. Create the directory structure: `wiki/`, `wiki/raw/`, `wiki/topics/`

- 3. Create `wiki/index.md` with a header and empty topic list

- 4. Create `wiki/.wiki-meta.json`:

- ```json

- {

- "created": "ISO-8601",

- "lastUpdated": "ISO-8601",

- "topicCount": 0,

- "sourceCount": 0,

- "totalWords": 0,

- "lastCompaction": null

- }

- ```

- 5. Output: "Wiki initialized at {path}. Add sources with `/wiki --add`."

+ Create `wiki/`, `wiki/raw/`, `wiki/topics/`, an empty `wiki/index.md`, and `wiki/.wiki-meta.json` with fields: `created`, `lastUpdated`, `topicCount: 0`, `sourceCount: 0`, `totalWords: 0`, `lastCompaction: null`. Default path: `wiki/` at project root.

### Command: `/wiki --add [source]`

Ingest a new source into the wiki.

- **Step 1: Determine source type**

- | Input | Action |

- |---|---|

- | URL | Fetch the page content using WebFetch, extract the main text |

- | File path | Read the file content |

- | Raw text (no URL or path detected) | Use the text directly |

- | No argument | Ask: "What would you like to add? (URL, file path, or paste text)" |

- **Step 2: Store the raw source**

- Write the raw content to `wiki/raw/source-{timestamp}.md` with a header:

- ```markdown

- # Source: {title or URL or "User Input"}

- > Ingested: {ISO-8601}

- > Type: {url | file | text}

- > Original: {URL or file path or "direct input"}

- {raw content}

- ```

- **Step 3: Extract topics**

- Read the raw content and identify 1-5 distinct topics covered. For each topic:

- 1. Check if a topic file already exists in `wiki/topics/` that covers this subject

- 2. If YES: append new information to the existing topic file under a new section

- 3. If NO: create a new topic file in `wiki/topics/{slug}.md`

- **Step 4: Write/update topic files**

- Each topic file follows this structure:

- ```markdown

- # {Topic Title}

- > Last updated: {ISO-8601}

- > Sources: {list of source files that contributed}

- {Compiled, structured content about this topic}

- ## Related Topics

- - [[another-topic]] -- {one-line description of relationship}

- - [[yet-another]] -- {relationship}

- ```

- Cross-links use `[[slug]]` notation. When writing or updating a topic, scan

- existing topics for potential cross-links.

- **Step 5: Update the index**

- Regenerate `wiki/index.md`:

- ```markdown

- # Wiki Index

- > Last updated: {ISO-8601}

- > Topics: {count} | Sources: {count} | Words: ~{estimate}

- ## Topics

- | Topic | Summary | Last Updated |

- |---|---|---|

- | [[topic-slug]] | {one-sentence summary} | {date} |

- | [[another-topic]] | {summary} | {date} |

+ **Step 1:** Determine source type — URL (fetch with WebFetch), file path (read), raw text (use directly), no argument (ask user).

- ## Recent Sources

+ **Step 2:** Write raw content to `wiki/raw/source-{timestamp}.md` with header: title/URL, ingested date, type, original reference.

- | Source | Date | Topics Generated |

- |---|---|---|

- | {source file} | {date} | {list of topic slugs} |

- ```

+ **Step 3:** Identify 1-5 topics. For each: check if a topic file already exists — append to existing or create `wiki/topics/{slug}.md`.

- **Step 6: Update metadata**

+ **Step 4:** Each topic file has: title, `> Last updated`, `> Sources`, compiled content, and `## Related Topics` with `[[slug]]` cross-links. Scan existing topics for cross-links when writing.

- Update `wiki/.wiki-meta.json` with new counts.

+ **Step 5:** Regenerate `wiki/index.md` with stats header, Topics table (`[[slug]]` | summary | last updated), and Recent Sources table.

- **Step 7: Output**

+ **Step 6:** Update `wiki/.wiki-meta.json` with new counts.

- ```

- Added to wiki:

- Source: {source description}

- Topics created: {list of new topics}

- Topics updated: {list of updated topics}

- Index updated: {topic count} topics, ~{word count} words

- ```

+ **Step 7:** Output: source description, topics created, topics updated, index counts.

### Command: `/wiki --query [question]`

- Answer a question using wiki knowledge. No embeddings -- LLM-native navigation.

- **Step 1: Read the index**

- Read `wiki/index.md` to understand what topics exist and their summaries.

- **Step 2: Plan navigation**

- Based on the question and the index, identify 1-5 topic files most likely to

- contain relevant information. Explain your reasoning briefly:

- ```

- Navigating wiki for: "{question}"

- Reading: [[topic-a]] (likely relevant because...), [[topic-b]] (covers...)

- ```

- **Step 3: Read relevant topics**

- Read the identified topic files. If a topic references another topic via

- `[[cross-link]]` that seems relevant, follow the link and read that too.

- Maximum depth: 2 hops from the index.

- **Step 4: Synthesize answer**

- Produce a clear answer citing the specific topic files used:

- ```

- Based on the wiki:

- {answer}

- Sources:

- - wiki/topics/topic-a.md

- - wiki/topics/topic-b.md

- ```

- **Step 5: Handle gaps**

- If the wiki does not contain enough information to answer:

- ```

- The wiki does not have enough information to fully answer this.

- What the wiki knows:

- - {partial information found}

- Gaps:

- - {what's missing}

- Suggestion: Add sources about {missing area} with `/wiki --add`.

- ```

+ 1. Read `wiki/index.md`, identify 1-5 relevant topic files, explain reasoning briefly

+ 2. Read those topics; follow `[[cross-links]]` up to 2 hops if relevant

+ 3. Produce a clear answer citing specific topic files used

+ 4. If the wiki lacks enough information: state what it knows, list gaps, suggest `/wiki --add` for missing areas

### Command: `/wiki --status`

- Detailed wiki health report.

- 1. Read `wiki/.wiki-meta.json`

- 2. Count topic files in `wiki/topics/`

- 3. Count raw sources in `wiki/raw/`

- 4. Check for orphaned topics (in topics/ but not in index.md)

- 5. Check for broken cross-links (referenced `[[slug]]` but no matching file)

- 6. Check for stale topics (not updated in 30+ days, if dates are available)

- Output:

- ```

- Wiki Status: {wiki path}

- Topics: {count}

- Sources: {count}

- Words: ~{estimate}

- Last updated: {date}

- Last compaction: {date or "never"}

- Health:

- Orphaned topics: {count} ({list if any})

- Broken cross-links: {count} ({list if any})

- Stale topics (30+ days): {count} ({list if any})

- Pending raw sources: {count of raw/ files not yet processed}

- ```

+ Read meta, count topic files and raw sources, check for orphaned topics, broken cross-links, and stale topics (30+ days). Output: topic/source/word counts, last updated/compaction dates, and health issues with counts and lists.

### Command: `/wiki --compact`

- Merge, deduplicate, and reorganize the wiki.

- **Step 1: Read everything**

- Read `wiki/index.md` and all files in `wiki/topics/`.

- **Step 2: Identify compaction opportunities**

- - **Merge candidates**: Topics that cover overlapping subjects and should be combined

- - **Split candidates**: Topics that cover multiple distinct subjects and should be separated

- - **Stale content**: Information that is outdated or superseded by newer content

- - **Duplicate content**: The same information appears in multiple topics

- **Step 3: Execute compaction**

- For each change:

- 1. Describe what will change and why

- 2. Make the change

- 3. Update all cross-links that reference renamed or merged topics

- **Step 4: Rebuild index**

- Regenerate `wiki/index.md` from the updated topic files.

- **Step 5: Update metadata**

- Update `wiki/.wiki-meta.json` with `lastCompaction` timestamp and new counts.

- **Step 6: Output**

- ```

- Compaction complete:

- Topics merged: {count} ({details})

- Topics split: {count} ({details})

- Stale content removed: {count}

- Duplicates resolved: {count}

- Final topic count: {count}

- Estimated words: ~{count}

- ```

+ 1. Read `wiki/index.md` and all topic files

+ 2. Identify: merge candidates (overlapping subjects), split candidates (multiple distinct subjects), stale/outdated content, duplicates

+ 3. For each change: describe what and why, make the change, update all affected cross-links

+ 4. Rebuild `wiki/index.md` and update `wiki/.wiki-meta.json` with `lastCompaction` and new counts

+ 5. Output: topics merged/split/removed/resolved, final count, estimated words

### Command: `/wiki --rebuild-index`

- Regenerate the index from current topic files without modifying topics.

- 1. Read all files in `wiki/topics/`

- 2. Extract title, first-sentence summary, last-updated date from each

- 3. Write a fresh `wiki/index.md`

- 4. Output: "Index rebuilt with {count} topics."

+ Read all topic files, extract title/summary/date, write a fresh `wiki/index.md`. Output: "Index rebuilt with {count} topics."

## Fringe Cases

- - **Wiki directory does not exist**: Prompt the user to run `/wiki init` first. Do not auto-create on query or status commands.

- - **Raw source is very large (>50K words)**: Split into logical sections before processing. Warn the user: "Large source detected. Processing in sections."

- - **Topic name collision**: If two sources produce topics with the same slug, merge the content into the existing topic rather than overwriting.

- - **Empty wiki queried**: Return "The wiki is empty. Add sources with `/wiki --add` to build the knowledge base."

- - **Cross-link target does not exist**: During compaction or index rebuild, flag as a broken link. During --add, create the missing topic if there is enough context, otherwise leave the link as a stub: `[[missing-topic]] (stub -- needs content)`.

- - **URL fetch fails**: Report the failure, suggest the user paste the content directly as text input.

- - **Wiki exceeds ~400K words**: Warn during --status: "Wiki is approaching the LLM context limit (~400K words). Consider archiving older topics or using `/wiki --compact` to reduce size."

+ - **`.planning/` does not exist**: Run `/do setup` first to initialize the harness state directory.

+ - **No wiki directory**: Prompt to run `/wiki init`. Do not auto-create on query or status.

+ - **Source >50K words**: Split into sections, warn the user.

+ - **Topic name collision**: Merge into existing topic, do not overwrite.

+ - **Empty wiki queried**: "The wiki is empty. Add sources with `/wiki --add`."

+ - **Broken cross-link**: During compaction/rebuild — flag. During --add — create stub `[[missing-topic]] (stub -- needs content)` if no context.

+ - **URL fetch fails**: Report failure, suggest pasting content directly.

+ - **Wiki >~400K words**: Warn during --status, suggest archiving or `/wiki --compact`.

+ ## Contextual Gates

+ **Disclosure:** "Updating wiki at `.planning/wiki/`. Files will be created or modified."

+ **Reversibility:** amber — creates and modifies `.planning/wiki/` files; undo by deleting or reverting changed files.

+ **Trust gates:**

+ - Any: all wiki commands (init, add, query, status, compact, rebuild-index).

## Quality Gates

- Every topic file must have a title, last-updated date, and sources list

- Every topic file must have at least one cross-link to another topic (unless it is the only topic)

- The index must accurately reflect all topic files (no orphans after --add or --compact)

- No duplicate topic files (same slug = same file)

- Raw sources are preserved in wiki/raw/ and never deleted

- The --query command must cite specific topic files, not fabricate information

## Exit Protocol

Output a summary appropriate to the command executed, then:

```

---HANDOFF---

- Wiki: {command executed} at {wiki path}

- Topics: {count} total, {new/updated/merged count} changed

- Status: {healthy | needs compaction | has orphans/broken links}

---

```