audit-docs

name	audit-docs
user-invocable	true
version	2.0.1
argument-hint	[--fix]
author	Gabriel Trabanco <[e-mail]>
license	MIT
description	Audit cross-document coherence: docs ↔ roadmap ↔ code ↔ fix index ↔ issues. Finds drift — features in docs/ not in the roadmap (or vice versa), fix-index entries already merged/closed, broken documentation-map links, dependency cycles, artifacts in the wrong language, naming-convention violations — and reports them ranked by severity, fixing only low-risk items on request. On Claude Code and want hand-tuned per-skill model/effort tiers? Install the `#claude` branch instead (`npx skills add gtrabanco/agentic-workflow#claude`) — see the README. This branch is model-agnostic: the skill inherits whatever model and effort your agent session is already using. Triggers: "check doc consistency", "are the docs in sync", "audit the docs", "doc coherence review", "did the docs drift", "validate the roadmap".

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).

Workflow discipline (checks 10–14) — the executor skills enforce these at write time; this audit verifies they actually held. Each check is mechanical: run the command shown, don't infer.

10. Phase naming. grep -rnE '\bS[0-9]+\b|\bStep [0-9]' docs/features/*/{PLAN,TASKS,progress}.md must return nothing — plans use P1, P2, … ("phases") only. Any hit: LOW (rename), plus check the executor argument still resolves.
11. Per-phase doc discipline. For every M/L feature in-progress/done: completed phases are ticked in TASKS.md, progress.md has one entry per completed phase, and (features planned under the current template) the final phase ends with the literal close-out tasks (open PR + print URL, link roadmap row, push the link commit). A done feature with unticked tasks or a phase missing from progress.md: HIGH.
12. Branch & PR discipline vs the forge. For every done unit: its PR exists, targets the default branch, has a non-empty body, and carries Closes #<n> when the unit is issue-born (SPEC references an issue). Also scan recent default-branch history (git log --first-parent) for feature/fix-scoped changes committed directly without a PR: HIGH.
13. Generated-docs provenance (only when the documentation map declares a Docs site block; otherwise state n/a). Scan the declared content dir for pages carrying generated-by: agentic-workflow/generate-docs. For each: (a) its source-unit exists in the roadmap or fix index — no match is an orphan (MEDIUM: propose deletion or re-attribution); (b) the unit's PR merged after the page's updated date with commits touching the page's subject paths — that page is stale (LOW: propose /generate-docs <unit> to refresh). Cite page path + unit per finding.
14. Commit format & dependency discipline. Sample the unit branches' commits: <type>(<scope>): <summary> conventional format (violations: LOW). Every in-progress/done row's Depends on: closure was merged — a unit built on unmerged deps is HIGH unless decisions.md records a user-forced override (--force), which downgrades it to LOW (documented risk).

Adapt the list to what the project has; skip checks for absent structures and say so.

Process

1. Discover, then run the checks with grep, file reads, and the forge CLI (per Workflow conventions; examples use gh).

2. Produce the findings report — return exactly (fixed output contract):

   AUDIT DOCS — scope: <docs tree / roadmap / fix index / issues checked>
   
   | # | Check (1-13) | Finding | Sev | Evidence | Proposed fix |
   |---|-------------|---------|-----|----------|--------------|
   | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
   
   Checks run: <n>/13 (skipped: <which + why — absent structures only>)
   Summary: <1-2 sentences>
   Decision: PASS | FAIL   (FAIL if any high-severity finding is open)
   

   Sev: high = misleading or broken; low = cosmetic.

3. Fix only on request. With explicit --fix (or user go-ahead), apply the low-risk corrections (remove a merged fix-index row, fix a dead link, register a missing roadmap entry, add a verified PR link to a bare done row). Leave judgment calls to the user.

Guardrails

• Read-first; never bulk-rewrite docs unprompted.
• Distinguish genuine drift from intentionally "scheduled/deferred" items — don't report deliberate tradeoffs as errors.
• Keep changes surgical and within docs; no code or behavior changes.

Portability (agents other than Claude Code)

The workflow is the contract; Claude Code features are conveniences. On an agent that lacks one, apply the fallback — never skip the step the feature enables:

• No slash-command menu — where this skill says /<skill>, open that skill's SKILL.md (wherever your agent installed the skills) and follow it literally, in a fresh conversation: hand-offs assume a clean context.
• No per-skill model:/effort: — on the #claude branch the frontmatter pins these tiers; here, pick tiers yourself: these are mostly mechanical cross-document checks — a mid-tier model is enough; escalate to your strongest only for a deep audit.

Relationship to other skills

• Complements plan-feature (which creates the docs this audits) and triage-issue (which keeps the fix index honest).
• Run standalone anytime; no required predecessor.

Done when

• A severity-ranked findings report exists, and any approved low-risk fixes are applied — with genuine deferrals left untouched and labeled as such.

• The closing → Next: block is printed:

  → Next: apply the approved low-risk fixes, then re-run /audit-docs to confirm clean
    · real drift (not cosmetic) → /triage-issue   · a concrete defect → /plan-fix
    · already clean → nothing to do