docs-auditlisted
Install: claude install-skill theogyeezy/skillz
# Docs accuracy audit — drift report first, then fixes with the same rigor
Living docs rot in a specific way: the big new system gets zero mentions (grep the flagship doc
for the system's name — count 0 is the classic), status lines fossilize ("pytest 193" while the
suite is thousands), completed migrations stay framed as in-flight, and one-time checklists keep
presenting shipped work as pending owner actions. Fix by AUDIT → APPLY → VERIFY-your-own-fixes.
## Procedure
1. **Scope split, before anything.** Living docs (claim to describe the present) vs dated
historical records (BUILD_STATUS sections, dated specs/plans, ops runbook logs, request-queue
entries). NEVER rewrite the historical set — banner it if misleading, otherwise leave it.
One-time artifacts (go-live checklists, point-in-time audits) get one of three verdicts:
edit (still load-bearing), banner ("historical — superseded by X"), or delete (both only if
every item is provably resolved, with citations).
2. **One read-only audit agent per repo, in parallel.** Each builds ground truth FIRST
(`git log --oneline --since=<last sweep>`, the build log's newest sections, the maintained
TODO, direct code reads), then reads every living doc fully and reports per file:
- the stale claim, quoted, with line number
- current reality, with the citation that proves it (commit/PR/code path)
- the concrete replacement text (or banner/delete)
- priority: P0 = actively misleading (drives a wrong dec