/doc-drift

Your README has been lying for six months. Time to catch it. Extracts verifiable claims from docs (paths, commands, config keys, endpoints, versions, symbol references) and statically checks each against the code reality.

What this is for

• README mentions commands that no longer exist, paths that moved, env vars that were renamed - nobody checks this systematically because it is tedious manual work at scale.
• Read-only skill. Documented commands are NEVER executed - purely static comparison (safety over completeness). No external links, no prose evaluation.

PROTECTION RULE - never ~/.claude/

Read-only skill. Guard required if write mode added later.

What You Must Do When Invoked

During analysis, assign a confidence level to each finding: proven (confirmed by evidence), likely (strong signal, needs review), or suspected (weak signal).

If /doc-drift -help or /doc-drift -h (without further arguments) is invoked: output the ## Usage section unchanged and stop.

Otherwise follow these steps in order, skipping none.

Step 1 - Help check

If invoked with -help or -h, output the ## Usage section unchanged and stop.

Step 2 - Clarify target

Clarify -ProjectDir. Get confirmation.

Step 3 - Scan

& "<SKILL_DIR>/scripts/claim-extract.ps1" -ProjectDir "<path>"

If docFiles is empty: inform the user that no doc files were found (README*/.md/docs/**/.md/CONTRIBUTING*), stop.

Step 4 - Verification (NEVER execute commands)

Check each claim statically against the repo (Grep/Glob/Read):

• path: does file/directory exist? On failure: search for similar paths (moved?) -> correction suggestion.
• command: match npm scripts against package.json scripts (analogous Makefile targets, pyproject scripts) - existence logic only, never execute. Not statically checkable -> not-checkable.
• config: grep key in code/config - is it read/defined?
• endpoint: does route exist in code?
• version: compare against engines/target entries in manifests.
• symbol: does identifier exist in code (word-boundary grep)?

Special cases: future announcements ("coming soon...") -> not-checkable, not drift. Placeholders (<your-key>, $VAR): normalize, only check structure. Monorepo: try path relative to doc directory AND repo root. Auto-generated docs (generator marker): exclude, only list. Anchor links (#section) not checked (out of scope).

Verdict per claim: correct / DRIFT (with both locations: doc line + repo evidence or absence) / not-checkable (with reason). Severity for drift: high (command/path in setup path) / medium / low.

Step 5 - Write report

File doc-drift-report.md in the current working directory:

1. Summary - total claims, drift ratio, high-severity findings.
2. Drift findings by severity, per finding: correction suggestion (concrete replacement text).
3. Not-checkable list.
4. Correct count.
5. Open questions.

Evidence requirement: each drift verdict with both locations.

Step 6 - Summarize

State the report path, drift ratio and high-severity findings first.

Usage

/doc-drift               # interactive
/doc-drift <dir>         # check repo docs
/doc-drift -help