docs-drift-guard
docs-drift-guard
Prose documentation drifts because nothing forces it to stay true: the code moves, the doc doesn't, and the rot is invisible until someone trusts a stale sentence. This skill is the methodology for making that drift either impossible (by construction) or loud (by a check), plus the ready-made floor check to drop into any repo's gate.
The principle
The more a doc is derived from or executed against code rather than hand-written about it, the less it can drift. Push every claim as far down this ladder as it will go; what's left as prose, keep at an altitude that rarely changes and guard the parts that can be checked.
| Rung | What it means | Drift outcome |
|---|---|---|
| Generated | the doc is a build artifact of the code (API/CLI/type reference) | can't drift |
| Executed | the doc's examples/claims run in CI (doctests, runnable snippets) | drift = red test |
| Checked | links, snippets, and structural rules verified mechanically | structural drift caught |
| Reviewed | humans/bots prompted to re-read when cited source changes | drift surfaced, not blocked |
| Prose | sentences nobody re-checks | drifts freely |
A doc is usually a mix: generate what you can, execute the examples, check the links and the invariants, and leave only genuine synthesis as guarded prose.