Writing a knowledge base note

1. Pick the type

If the answer is "none of these", it probably does not belong in the knowledge base. Something derivable from the code or from git history is not a note.

2. Read the template first

Read kb/<folder>/_template.md before writing. Every folder has one, and the sections in it are not suggestions — the queries in index.md and the checks in verify.py both depend on the shape.

Do not reconstruct the structure from memory, even if you have written one before.

3. Gather what the template needs

Ask for what is missing rather than filling it in plausibly:

• Decision — context, the decision itself, the alternatives with the specific reason each lost, consequences. An alternative listed without a reason is decoration.
• Incident — symptom exactly as observed, root cause (or open if genuinely unknown), the fix, and something executable that prevents recurrence. "Be more careful" is not prevention.
• Research — the question, findings each attributed to a source, then the recommendation in its own labelled section.

A guess recorded as a root cause is how the same incident gets investigated twice. Leave it open instead.

4. Name and write it

kb/<folder>/<slug>.md, date-prefixed where the type is dated by nature. Research notes are named by domain instead. Same-day collisions get a numeric suffix — never overwrite.

Frontmatter is mandatory: date, tags, status, plus related_spec when a spec applies (omit the key entirely when it does not).

Write in the language the project uses for its notes — check an existing note or bootstrap.yaml.

5. Then offer the index update

Only after the note exists, and only as a surgical edit to the one section that changed. Show the user the exact line you propose adding and let them approve it.

kb/index.md gets a snapshot of two or three lines and a link — never a copy of the note's reasoning. If the project has Dataview enabled, the note may already appear in the generated lists, in which case no manual edit is needed at all; check before proposing one.

Rules

• Never write a whole file without reading the existing one first.
• A published note is appended to, never rewritten: **Update YYYY-MM-DD**: <what changed>.
• A superseding decision is a new note that says what it supersedes; the old one gains a forward pointer and keeps its content.
• Resolved items in living lists are struck through, not deleted.
• Link with [[wikilinks]] instead of repeating text across notes.
• Before setting status: resolved on anything involving concurrency, timing or reproducibility: an independent re-run is required. A self-report is not evidence.