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.

The floor: @onsager/docs-drift-check (the Checked rung, every repo)

The cheapest enforced rung: assert that every repo-relative link/path a doc cites still resolves. Deterministic, zero-dependency, no LLM, safe as a blocking gate — and it ignores links inside code fences so example snippets never trip it.

npm i -D @onsager/docs-drift-check
npx docs-drift-check 'docs/**/*.md' README.md      # exit 1 on any dead path
npx docs-drift-check --external 'docs/**/*.md'      # also HEAD-check http(s) links (opt-in)

Wire it into the repo's existing gate — whichever the repo already runs:

• node:test repos — a thin wrapper so it runs with the suite:

  import { test } from "node:test";
  import { execFileSync } from "node:child_process";
  test("docs cite no dead paths", () =>
    // npx --no-install resolves from node_modules/.bin; a bare bin name only
    // works when PATH already has it, which plain `node --test` doesn't guarantee.
    execFileSync("npx", ["--no-install", "docs-drift-check", "docs/**/*.md", "README.md"], { stdio: "inherit" }));
  

• any repo — a package.json script or a CI step: docs-drift-check 'docs/**/*.md' README.md.