kb-write git:20261020.d000e38A

Immutable. This exact content never changes and is served at /api/v1/blob/54fde2e15a0fcedf.

---
name: kb-write
user-invocable: false
description: Write to the {{slot:product}} knowledge base - add new knowledge or update stale knowledge in {{kb.core}} (cross-cutting) or {{kb.features}}/<area>.md (one area, with F-NN feature rows). Use when asked to document, write down, or update architecture, a feature, a subsystem, a decision, an invariant, a how-to, or a reference fact; or when a finished feature, refactor, fix, rename, or move changed how an area works.
---

# /kb-write: add or update knowledge

`/kb-write <topic>` writes about one topic. `/kb-write` with no topic sweeps the current change: run `{{slot:kb-command}} changed` (against `HEAD`; add `-Base {{repository.baseBranch}}` for a whole branch) and handle every section and feature it lists whose subject actually changed.

Read `{{kb.root}}/maintenance.md` once per session (the core's "How to maintain this file" points to it); it holds the templates, conventions, and budgets.

## Where it goes

| The fact is... | Goes to |
|---|---|
| A user-facing feature: how it is triggered, its entry point, telemetry, and tests | A row in its area file's `## Features` table, with the next free `F-NN` across all files |
| How one area works: flow, entry points, key types, its lessons | A `##` section in `features/<area>.md` |
| A rule or recipe that only one area needs | A `##` section in that area file |
| Which sections to read before editing a folder or file pattern | A row in `{{kb.root}}/file-map.md`, linking the narrowest section that owns the files |
| How the app is composed ({{slot:write-composition}}) | `## Subsystems` in `composition.md` |
| A choice with lasting impact and a reason | A `## D-NNN Title` section with the next number across all files: in the area file if only one area needs it, otherwise in `decisions.md` |
| A rule every area must keep, with why and what breaks | `## Invariants` in `composition.md` |
| A short rule every change must keep | `## Architecture rules` in the main file |
| A recipe any area uses | `## How-tos` in `how-tos.md` |
| A stable table of paths, binaries, or configuration keys | `{{kb.root}}/references.md` |
| CI, CD, versioning, release and merge scripts, {{slot:write-tooling}} | `{{kb.root}}/tooling.md` |
| A bug, its root cause, and the fix | `{{kb.lessons}}` (Problem, Root cause, What fixed it, Takeaway), then a `- Lesson: <heading>` line in the owning section |
| A task, plan, status, or roadmap item | {{slot:write-plans}}, not the knowledge base |

Not knowledge: test counts, PR numbers, "verified on my machine", what was tried and abandoned, anything derivable from `git log`.

## Steps

1. Look first: `{{slot:kb-command}} read <topic or file>`. If a section already covers it, update that section instead of adding a near-duplicate.
2. Read the code before writing. Every path you name must exist; every claim about behavior comes from the code, not from memory. Say why, not only what.
3. Write it in the file from "Where it goes":
   - Main file: a `### <Title>` section at the end of the right `##` group.
   - Area file: a `## <Title>` section, or a row in `## Features`. A new area is a new `features/<area>.md` with `# <Area>`, a one-line scope, and `## Features`.
   - Updating: rewrite stale sentences in place; never append "Update:" or "Correction:" paragraphs.
4. End a section with a `**Files.**` line, `See [...](...)` links (another file's section is `other.md#anchor` or `../knowledge-base.md#anchor`), and `- Lesson:` lines with exact `{{kb.lessons}}` headings.
5. Keep the maps true in the same change:
   - A new, removed, or rewired feature{{slot:write-feature-triggers?}}: update its `F-NN` row. IDs are never renumbered or reused; a removed feature's ID stays retired.
   - A new, renamed, or moved folder or project: add or rewrite its File map row; link new sections from the rows whose files they describe.
   - A reversed decision: a new `## D-NNN`, and "Superseded by D-NNN" as the first line of the old one.
6. Stay inside the budgets: a section under 8192 bytes (a `###` section counts its parent `##` preamble), the main file under 12288, an area file under 40 KB. `check` fails on a new or grown violation and lists the existing ones in `{{kb.baseline}}`, so write into a section that fits or split a topic into `###` sections; never grow a listed section. Prefer tables and short lists. Dates are absolute; no status badges, and no changelog phrasing ("since 2026-...", "added ...", "As of ..."): state the current fact.
7. If you compared every section against the code, move "Last full review" at the top of the main file to today.
8. Finish with `/kb-check`. Report what was added, what was updated, and anything you saw but left alone.

`CLAUDE.md` gets at most one line per topic; detail lives in the knowledge base. Nothing is committed; the user reviews and commits.