documenting-code

Documenting Code

Turn implementation facts into docs that a named reader can use. Every claim in the result matches the code, and every visual renders cleanly.

Pick the mode

• Update: a code change made docs stale. Change the smallest set of docs. Done when each changed behavior is documented where its reader looks, and nothing unrelated changed.
• Overhaul: the user asks to rewrite, restructure, or improve a doc set, for example a README front page, guides, or an architecture doc. Done when:
  • each doc has one reader and one job, and each fact has one owner
  • every claim matches the code, and every visual passes its render check
  • the gate passes
• A named doc or a named change is enough scope; start work. Ask only when the request names neither, with one question and these options: auto-detect from recent changes, README, API docs, or the full doc set.

Readers

Decide the reader before writing.

• Human: short, scannable text. Use a diagram, table, or chart when it answers a question faster than prose. Load references/doc-set.md only for doc-set structure or Overhaul mode, references/style.md when rewriting prose, and references/visuals.md only when changing diagrams or charts.
• Agent (AGENTS.md, CLAUDE.md, skills, prompts): terse operational text with headers, bullets, numbered steps, exact contracts, and a table where it is the clearest form. No diagrams or rationale that a model already knows. To score or lint instruction files, use reviewing-instructions.
• Code: comments and docstrings state contracts, invariants, side effects, errors, and non-obvious decisions. Delete comments that restate the code. Load references/code.md for shared comment rules and per-language doc checks.

Workflow

1. Scope the work from the request and the changed files (git diff --name-only), and find the existing docs that cover them.
2. List the doc files, the reader and the job of each, and the facts that more than one doc states. In Overhaul mode, write the ownership map from references/doc-set.md before editing.
3. Read the code, tests, and configuration that each doc describes. When docs and code conflict, report it and update the docs to the code, unless the user says that the doc is the intended contract.
4. Write. Keep each fact in one place and link to it from the others. Replace adjectives with measured facts. Name actors, conditions, and referents; use one term per concept. Cut words only when meaning and necessary context survive.
5. Check changed claims against their source; use references/claims.md for configuration, API, or measured-performance claims. Generate sample output when changing examples. Mark unconfirmed claims and say where you looked.
6. If visuals changed, load references/visuals.md, render them, inspect the images, and fix the faults.
7. Run the gate once. Run it again only after further edits.
8. Report with the output contract.