khosra/.claude/commands/refresh-docs.md

description

description
Reconcile the docs against the actual code and report drift

Reconcile documentation with reality. The code is the truth; the docs are the suspects.

1. Inventory the actual Go files, their line counts, and the non-stdlib dependencies in go.mod.
2. Compare against docs/state.md: inventory rows, counters, latent items, verified against. Recount the counters from the code — number of render transforms, routing cases, views, output formats, extensions — rather than trusting the recorded numbers.
3. Check docs/architecture.md STATUS lines: has a primitive become real, or is one described as live when it is not built?
4. Check docs/content-model.md [spec] versus [live] markers against what the parser actually accepts. Frontmatter fields the code reads but the doc omits are drift; fields the doc promises but the code ignores are worse drift.
5. Check scripts/allowed-deps.txt against go.mod.
6. Look for facts stated in two docs. Delete one, link to the other.
7. Run ./scripts/verify.sh --list and check every doc sentence claiming a gate against it. A doc that says "verify.sh fails on X" where no such gate exists is the most damaging drift there is: it reads as enforcement and is decoration.
8. Check the reverse too — a gate in the list that no doc explains. Either document it or delete it.
9. Follow every cross-doc citation of a section ("see roadmap.md Governors", "CLAUDE.md §6") and confirm the heading exists. Whole sections have gone missing while another doc still cited them.

Scope: the docs listed above and nothing else. Do not open ideas/ or reference/ — they describe proposals and facts, never the state of the code, so they cannot be drifted against it. verify.sh already checks their indexes mechanically.

Then:

• Fix the docs. Doc-only diff; no code changes in this pass, no matter what you find.
• Anything in the code that contradicts an ADR: report it, do not silently document it as correct. A drifted invariant is a bug, not a new decision.
• Report drift found, drift fixed, and anything that needs a human decision.