documentation

Documentation

Documentation keeps a codebase accessible to reviewers and future maintainers — load-bearing in a spec-driven workflow. Its failure mode is not absence but rot: confident prose no longer matching the code. Hold docs to two standards at once: accessible (newcomer orients in minutes) and maintainable (every claim re-verifiable against code).

Use This Skill When

• Writing or restructuring a project's README, docs/ tree, or doc site
• Reviewing whether a change's documentation is adequate and current
• Auditing existing docs for staleness, missing synthesis, or missing diagrams
• Documenting an interface's behavioral contract — side effects, statefulness, idempotency, failure semantics — in docstrings or endpoint descriptions
• Setting up or judging formal doc tooling (OpenAPI, MkDocs, Sphinx, ReadTheDocs, docstring-generated references)

Do Not Use This Skill For

• Five-pillar knowledge architecture (doctrine, contracts, specs, topology, standards) — /th-projects (project-shape). This subskill governs the everyday docs of any repo, shaped or not.
• Skill packages — skill-standards
• Code comments — code-readability

Core Rule

Document the contract; cite the code. Every documented fact is a claim about the code: couple it to the location it derives from, and state it at an altitude where only a behavior change — never a behavior-preserving refactor — can falsify it. A doc that cannot be re-verified is already rotting; a doc narrating internals re-rots on every refactor.

The Bar

Cite the item violated, with doc and code evidence:

1. A concise synthesis orients first — Top of README.md or the docs/ intro states, in a screenful: what the project does, who it is for, goals and non-goals, how the pieces fit. Missing or buried synthesis is the highest-severity finding.
2. Diagrams wherever structure beats prose — Architecture, happy-path data flow, error handling, and lifecycle/state each get a diagram when the project has real structure there. Generate via excalidraw-diagram; commit .excalidraw source plus rendered SVG beside the embedding doc; fall back to Mermaid. Real component and event names — never generic boxes.
3. Facts carry citations to interface sites — Each claim links the code making it true (path/to/file.py:Symbol), anchored at definition and interface sites — module, endpoint handler, schema — never internal call chains. Prefer symbol anchors over line numbers. Uncited claims and stale citations are findings.
4. Claims survive behavior-preserving refactors — If a behavior-preserving refactor would falsify a claim, it documents internals: raise it to what callers observe, or delete it.
5. Public interfaces carry a semantics card — Endpoints, exported functions, jobs, and CLI commands document side effects, state, idempotency, failure, and (where it matters) concurrency as a few labeled lines adjacent to the interface, per references/interface-semantics.md.
6. Docs operate under a maintenance contract — The docs entry point states it: behavior changes update affected docs in the same change (engineering-bar bias 7); stale claims get fixed or marked STALE with evidence, never left silently. Living catalogs open with their own write-back contract.
7. Prose earns its place — Types, names, and defaults already document; prose states only what they cannot: semantics, invariants, units, the why. Every doc has a nameable reader and a question it answers — can't name both, delete or merge it.
8. Formal doc tooling serves human readers — OpenAPI/MkDocs/Sphinx output is judged as prose: human-written summaries, intent and failure modes, happy-path examples. Schema dumps, empty autogenerated stubs, and boilerplate padding are findings. Concise beats complete.
9. Content lives at the right distance — Structure follows the reader's journey (orient → run → how it works, where diagrams live → change → reference); placement follows the gradient: semantics at the interface, architecture in docs/, synthesis in the README. Wrong-distance and twice-homed content are findings.

Workflow

1. Inventory — README, docs/ tree, doc-site config, embedded diagrams; note what is generated and what claims to be current.
2. Synthesis first (bar 1) — Draft or fix it before judging anything else; keep it a screenful.
3. Diagram pass (bar 2) — List the architecture/data-flow/error-handling shapes the project actually has; generate missing high-value diagrams; embed them where the prose discusses that structure.
4. Citation and altitude audit (bars 3–4, 6) — Trace claims to code (all in review scope; a sample in a repo audit); label each cited-and-true, stale, uncited, or wrong-altitude. Fix in scope; add the maintenance contract if absent.
5. Semantics-card audit (bar 5) — Each public interface in scope has a card, adjacent to its definition, matching the code. A wrong card is worse than no card.
6. Rendered-output pass (bars 7–9) — Read as the intended consumer; flag schema dumps, signature-restating prose, empty stubs, and wrong-distance content; fix what is in scope.
7. Verify — Build the doc site (broken builds and dead links are findings); re-read the synthesis end-to-end after edits.

Trigger Sanity Check

• Should trigger: "Document this service so a reviewer can follow the data flow", "audit docs/ for stale claims", "our Sphinx site is a schema dump".
• Should not trigger: "Bootstrap the five-pillar knowledge architecture" (/th-projects) or "review this SKILL.md" (skill-standards).