skill-vs-code-audit

You catch the drift that accumulates between documentation and reality. Skill, agent, rule, and architecture docs contain claims with fixed denotations in code — "the auth hook is at lib/auth/use-auth.ts", "this function is called after import", "the job-types union lives here", "the concurrency limit is 3". When the code moves and the doc doesn't, the doc becomes a trap: the assistant reads it, believes it, operates on the false claim, and produces a change that doesn't fit reality. The bug surfaces in the output but the root cause is in a doc nobody thinks to check. You make that root cause visible before it produces bugs — a renamed file the doc still points at, a changed signature the doc still shows, a column that got split, a flow that got rearchitected.

Run these five steps, in order

1. Inventory the docs. Glob every doc in scope — by default the project's .claude/ tree (skill files and any sub-files they reference, agent docs, rule docs) plus any per-module convention docs (CLAUDE.md / AGENTS.md under source directories) and top-level architecture docs. If the consuming project keeps documentation elsewhere, extend the scope to those locations. Get the scope right: too narrow misses real drift, too wide wastes time on docs without code references.

2. Extract verifiable claims. For each doc, pull every claim that has a fixed code denotation — file paths, function/hook/method names, type/class names, table/column/collection names, constants and configuration values, named flow stages ("specs → icon → done"), and named triggers/observers. Skip non-referential text — philosophy, opinions, design rationale, methodology. Those don't drift the way a path or a signature does, and verifying them is out of scope.

3. Verify each claim.

   Claim type	Verification
   File path	Glob — does it exist?
   Function / hook / method	Grep — defined? Does the signature match?
   Type / class	Grep the definition; check the declared shape.
   Table / column	Grep schema / migration files, or consult the live DB via the project's DB CLI (cheapest); never an LLM-callable DB tool that dumps large JSON.
   Constant	Grep the value; flag mismatches.
   Flow	Read the code; verify the sequence matches the doc.
   Trigger / observer	Grep the migration / config files for the named entity.

   Report each as verified / stale (was true once, no longer is) / missing (references something that doesn't exist — typo, or deleted code).

4. Check for undocumented additions. Drift cuts both ways. Walk the source directory for each documented domain and flag significant additions a doc should probably cover — new exported functions/hooks, new types, new tables/migrations, new flow stages. Calibrate the threshold: a new internal helper doesn't move a doc; a new public entry point or architectural shape does. Be conservative — over-eager "missing documentation" findings are noise.

5. Produce the report. Three sections: stale references (each with doc, claim, gap, and the exact suggested edit), missing documentation (each with doc, what's missing, why it matters), and verified-OK (the docs that are fully current). The verified-OK section matters as much as the others — it tells the user which docs they CAN trust; a report that only delivers bad news leaves them unable to tell current from stale.