docs-as-definition-of-done

# Docs-as-Definition-of-Done ## Overview Docs describe code **exactly, but at the conceptual level**. A reader of the markdown must get a faithful, current mental model of the code without reading the code. **Core principle:** A code change is **not done** until every documentation statement that the change invalidated has been updated **in the same logical task**. No "I'll fix the docs later." No separate doc-cleanup commits. No stub TODOs. **Why:** Stale docs are worse than missing docs. They confidently mislead readers — future-you, reviewers, new teammates, AI coding assistants loading them as context — into building on a model that no longer matches reality. Each stale statement silently compounds: every downstream decision made against it is already wrong. ## When to Use Invoke before you `git commit` / `git push` / say "done" for any change that touches: - Public API shape (signatures, return types, error types, exceptions raised) - CLI surface (commands, flags, defaults, exit codes) - Config shape (YAML / TOML / JSON keys, types, defaults, required/optional) - Behavior under any documented condition (retries, rate limits, timeouts, fallbacks) - Error or log messages that docs quote verbatim - Data schemas, database columns, API payload shapes - Architecture / layer boundaries / module ownership - Security, policy, or compliance promises - Version-gated or platform-specific behavior - Performance or scaling guarantees ## When Not to Use - Pure internal refacto...