audit-docs

Audit Docs

A read-first audit answering "do the docs still match reality?" Produces a findings report; it does not silently rewrite docs.

Turn contract — verify before ending the turn

✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS | FAIL`
✓ No doc was rewritten without explicit --fix / user go-ahead
✓ The closing `→ Next:` block is printed as the ABSOLUTE last output

About to end the turn with any box unchecked? The turn is NOT done — complete the missing box first (weak models drop end-of-document duties; this list is first on purpose).

When to use

• Before a release or milestone, after merging several features/fixes, or whenever the doc set might have drifted from the code and issues.

Step 0 — Discover the project (always first)

Per the agent guide's Workflow conventions + documentation map, then read what THIS skill needs: the roadmap, the fix index + template, and the feature folder layout — the map tells you which links and invariants to check.

Checks

Run these and collect findings (cite paths/lines/issue numbers each):

1. Roadmap ↔ feature folders. Every docs/features/<NN>-<slug>/ is in the roadmap, and every roadmap entry has a folder (or is explicitly "scheduled").
2. Feature dependencies. SPEC Depends on / Branch fields are valid; no dependency cycles; ordering is consistent with the roadmap.
3. Fix index hygiene. Every entry maps to an open issue and an unmerged branch; flag entries whose issue is closed or whose PR merged (should have been removed). Flag open fix branches missing from the index.
4. Documentation-map links resolve. Every file the map references exists; flag "scheduled, not yet authored" items so they aren't mistaken for drift.
5. Broken intra-doc links. Relative links/anchors point at real files/sections.
6. Issue references. Acceptance/known-issues lines referencing #N aren't pointing at long-closed issues without note.
7. Language & naming conventions. Artifacts in the project's docs language (this repo: English); file/dir naming matches conventions (e.g. kebab-case TS files, PascalCase components).
8. Invariant tags. If the project uses invariant/decision IDs (e.g. INV-/D-/KI-), spot-check that referenced IDs exist where claimed.
9. PR-link integrity on done rows. Every roadmap row (and fix-index entry) with status done carries a linked PR reference — done · [#<pr>](<pr-url>). For each bare done, find its PR in the forge (gh pr list --state all --head feat/<NN>-<slug> or by title) and propose the row update; a done with no PR found at all is HIGH severity (the unit may never have been closed out).