to-wiki

Files (6)

• SKILL.md
• gate-review.md · references/
• lint.md · references/
• schema-template.md · references/
• structure-selection.md · references/
• test-record.md · references/

SKILL.md (first lines)

# Source → LLM Wiki

## Overview

A wiki is a **second layer over an immutable raw source**. Raw stays verbatim in `docs/references/`.
The wiki holds hand-written pages that summarize, cross-link, and synthesize, and every fact in it
points at the raw line it came from.

**Core principle: the wiki may only know what the source says.** If a fact is not in the raw text,
the wiki does not state it. The only place an absent topic may appear is a `## Not covered by the
source` list at the end of a concept page. That list is the valve that keeps writer knowledge out.

A wiki built without that valve fills with plausible outside facts within pages. Measured in the
baseline for this skill: the writer defined a `Background` tag, "true, standard, and not in the
source", and used it on the first method page.

## When to Use

- Raw source already transcribed to Markdown (use `to-markdown` first if not).
- Output will be queried by agents and people later, and will grow as more sources are ingested.
- Someone will trust a number or a claim from a wiki page without reopening the raw file.
- An existing wiki needs an ingest, a query answered from it, a lint, or a pre-handover review.

**When NOT to use:** one-off question about a document → read it and answer. Notes for one
session → a scratch file. Source not yet in Markdown → `to-markdown` first.

## The Output Contract

Not guidelines. The shape of the deliverable.

| Part | Content |
| --- | --- |
| `AGENTS.md` | Schema: layout, hard rules, link paths, frontmatter, page templates, index and log formats, ingest / query / lint workflows, frozen slug list |
| `index.md` | One line per page, grouped by type, alphabetical. Loaded first by any agent |
| `log.md` | Append-only, dated entries: `ingest`, `query`, `lint`. Newest at bottom |
| `sources/` | One page per raw document, plus one per chapter. Section-by-section map with anchors, equations table, figures table, numbers table, citations table |
| `concepts/` | One idea per page. Ends with mandatory `## Not covered by the source` |
| `entities/` | People, orgs, hardware, software, papers, deployments. An index into the source: `## Every mention` bullets, not an encyclopedia article |
| `syntheses/` | Cross-page answers: comparisons, equation index, figure index, key numbers, lessons, contributions map, open problems |

Page rules that are non-negotiable, in the schema and on every page:

1. **Every claim sentence carries an inline relative link to its raw section anchor.** A page-level
   "Source lines" footer is not enough. Baseline: one footer-only page had 96 unanchored sentences
   and one invented count ("five of six") that the footer could not have caught.
2. **A citation clause is all you get.** If the source gives a cited work only a number and a clause,
   the wiki gets only that clause. No method summary from memory.
3. Numbers exact, with units. Equations copied byte-exact with the source's own tag.
4. Cross-link on first mention. At least 3 outgoing wiki links per page. Relative Markdown links only.
5. Figures link into raw assets. Never copy images.
6. Where the source is silent, write "the source does not say". Where the wiki draws a connection
   the source does not draw, label it "wiki reading".
7. Pages hold latest state. History goes to `log.md`.
8. **Entity threshold.** An entity page exists only for a work, person, or thing the source describes
   in more than one clause or gives a role. A work cited once stays a row in the source page's citations
   table. On a review with ~180 references this rule removes most stub pages.

Template for the schema file, ready to adapt: [references/schema-template.md](references/schema-template.md).

## Process

```dot
digraph wiki {
    rankdir=TB;
    "Read the whole source" [shape=box];
    "Inventory pages + gap-check" [shape=box];
    "Write schema + skeleton" [shape=box];
    "Parallel writers by provenance" [shape=box];
    "Own review pass vs raw" [shape=box];
    "Index, log, lint" [shape=box];
    "Gate: one reviewer per dimension" [shape=box];
    "Defects?" [shape=diamond];
    "Editors on disjoint folders" [shape=box];
    "Handover" [shape=box];

    "Read the whole source" -> "Inventory pages + gap-check" -> "Write schema + skeleton";
    "Write schema + skeleton" -> "Parallel writers by provenance" -> "Own review pass vs raw";
    "Own review pass vs raw" -> "Index, log, lint" -> "Gate: one reviewer per dimension" -> "Defects?";
    "Defects?" -> "Editors on disjoint folders" [label="yes"];
    "Editors on disjoint folders" -> "Index, log, lint";
    "Defects?" -> "Handover" [label="no"];
}
```

**1. Read the whole source yourself.** All chapters, bibliography, reference cards. The inventory
you design next is only as good as your recall of what is in the text.

**2. Inventory the pages, then gap-check the inventory.** Choose the shape for this kind of
source first, with [references/structure-selection.md](references/structure-selection.md): what
earns an entity page, which syntheses are mandatory, how the concept template changes, which gate
lenses run. Then draft slugs per type. Then dispatch one planning agent with the draft and the raw paths, and ask for: topics the source states that no
page covers, pages to merge (too thin) or split (too fat), pages that will tempt outside knowledge,
and a batch split by chapter provenance. In the run that produced this skill the gap-check added
10 pages (a method step, test setup, dataset, committee members, a cited-work entity), merged
6, split 2, and named 10 risk pages that later got sentence-by-sentence review.

**3. Write the schema and skeleton first.** `AGENTS.md` with every rule above and the **frozen
slug list**. Empty `index.md` with type headings. `log.md` header. Writers link against the frozen
slugs, so cross-batch links do not dangle.

**4. Parallel writers, split by chapter provenance, never by folder.** One writer per chapter
group, so no two writers need the same raw section open. Each gets the schema, the frozen slug
list, its own slugs with one-line intent each, and the raw files to read. Nobody touches
`index.md` or `log.md`. Each returns its index lines in its final message. Model: `opus`.

**5. Read every page yourself against its raw anchors.** Look for: numbers, outside knowledge on
the risk pages, inferences stated as fact, ambiguous dropped articles, template compliance. This
pass is authorship. It does not replace step 7.

**6. Assemble index and log. Lint.** Broken links, bad anchors, frontmatter, index coverage, title
match, minimum links, `Not covered` present, encoding. Shell one-liners in
[references/lint.md](references/lint.md). No generator scripts, no checker scripts inside the wiki.

**7. Gate: one reviewer per dimension, before any handover.** See below. Required.

**8. Editors on disjoint folders, then lint again, then log.** Style and consistency fixes are
large. Two `opus` editors, one per folder pair, with hard rules: no fact, number, link, heading,
or quoted text changes. Then re-run step 6 and append a `lint` entry to `log.md`.

From bmad-labs/skills, MIT.

More from bmad-labs/skills