doc-consistency-check

Purpose

Documentation rots when code changes. This check finds stale references in Markdown files — paths, commands, package scripts, env names, links — and flags them for immediate correction.

When to Use

• After a refactor that renamed or moved files, scripts, or env vars
• A reader followed the docs and a command or path failed
• Periodic doc hygiene before a release

Inputs

• The documentation set (Markdown files across the repo, not just the README)
• The current repo state to validate against

Workflow

1. Inventory the docs and extract referenced paths:

   git ls-files "*.md"                                                      # full doc inventory
   rg -no "[A-Za-z0-9_-]+/[A-Za-z0-9_./-]+\.[a-z]{2,4}" README.md docs/    # path-like references

2. Verify referenced files still exist in the repository. If not, the documentation is stale:

   test -f src/components/Button.tsx || echo "STALE: src/components/Button.tsx"

3. Verify documented commands against reality. Package scripts, CLI invocations, and env names must match the current source:

   rg -no "npm run [a-z:-]+" README.md docs/ | sort -u    # documented scripts...
   rg -n "\"scripts\"" -A 20 package.json                 # ...vs actual scripts
   rg -no "[A-Z][A-Z0-9_]{3,}=" docs/ | sort -u           # documented env names vs config source

4. Check code blocks in documentation. Do the function names and variable names still match the actual source code?

   rg -n "functionNameFromDocs" src/ || echo "identifier not found in source"

5. Check links. Relative links must resolve to existing files; flag external links that obviously moved.
6. Flag everything for immediate correction. Fix in place when the right value is unambiguous; report the rest with file and line.

Output

• A stale-reference report grouped by type (paths, commands, scripts, env names, links), each with doc file:line
• Fixes applied where the correct replacement is unambiguous

Verification

• All Markdown files inventoried, not just the README
• Every doc-referenced path tested for existence
• Documented scripts and commands compared against the actual manifest/CLI
• Code-block identifiers spot-checked against source
• Each finding fixed or reported with file and line

Failure Modes

• README-only pass — the rot usually lives in docs/ and subsystem files, not the front page.
• Existence-only checking — a path can exist while the command or identifier on the same line is stale.
• Guessed fixes — when the correct replacement is ambiguous, report it; do not invent one.