docs-reality-auditlisted

# Docs Reality Audit ## Truth Hierarchy ``` Live code/config > package.json/tooling output > git log recency > docs ``` Docs are never truth — they're a claim about truth. A doc that reads as authoritative (dated, "Status: Active", specific line numbers, structured tables) is not more likely to be correct than a stale one. Verify every load-bearing claim against the thing it describes before trusting it. ## When to Use The user wants documentation simplified, "brought up to date," or reviewed for accuracy — not just tidied. Also use proactively when a doc's own internal evidence (a "last updated" date far behind recent commits, a status note contradicted by the file tree) suggests drift. ## Process ### Phase 1 — Inventory + Recency Signal ```bash find <repo-root> -iname "*.md" -not -path "*/node_modules/*" -not -path "*/archive/*" | sort git log -1 --format=%ad --date=short -- <doc> # doc's last touch git log --oneline -15 # what's actually been happening lately ``` Compare doc last-touch dates against recent commit activity in the areas they describe. A doc untouched while its subject area has 10+ recent commits is the highest-probability drift candidate — read it first. Also check local-vs-tracked drift before reading content: `git status` + `git diff origin/main --name-only`. A doc file present locally but not in git (or vice versa) needs reconciling before you audit its content — you could otherwise be auditing a file n