documentation-lifecyclelisted

# Documentation Lifecycle Documentation is the one artifact a coding agent produces that **nothing checks**. Code has a compiler, a type-checker and a test suite; prose has a reader who assumes it is true. That asymmetry is why AI-written docs go wrong in a specific, boring way — they name functions, flags and files that do not exist — and why this skill exists as machinery rather than advice. Four steps, and only the middle one is judgment. ## 1. Register before you write (`doc_register`) A doc is registered with its **subject**, **owner** and **source files** *before the prose exists*. That inverts the usual order for a reason: a catalog built from files that already exist can only describe what somebody already wrote, so "nobody has documented the payment flow" stays a discovery instead of becoming a query. The source set is also what makes the doc checkable at all. A doc anchored to no code can never be stale, which sounds like a feature and is the opposite — `doc_freshness` reports those separately as a gap, not a pass. ## 2. Gather, then think, then write — in that order The failure mode is writing first and looking things up to justify it. Collect the sources (`graph_query`, `explain_node`, the files themselves), form the explanation, *then* draft. When an external API is involved, get its **current** shape (`references/core/knowledge-sources.md`) rather than its training-cutoff shape. **Never bootstrap truth from generated docs.** An agent-written doc is a *de