/audit-docs

name: audit-docs
user-invocable: true
version: 4.10.0
argument-hint: "[--fix]"
author: "Gabriel Trabanco <1969593+gtrabanco@users.noreply.github.com>"
license: MIT
description: >
  Audit cross-document coherence: docs ↔ READMEs ↔ 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,
  project-charter coverage — and reports them ranked by severity, fixing only
  low-risk items on request.
  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

> **Runner commands** below are `bunx @gtrabanco/agentic-workflow@<pin> …` — read `<pin>` > from [references/RUNNER.md](../runner-contract/references/RUNNER.md). It is stamped at > release and never guessed: a hard-coded version re-opens the per-release sweep the > contract removes, and `latest` is not a legal pin.

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

Turn contract

Load and verify the **canonical** [Turn contract](../orchestration-envelope/references/TURN_CONTRACT.md) (11 boxes) before ending every turn (the `--fix` path commits and pushes like any editing turn). Skill-specific additions (the `→ Next:` box is canonical-owned and not restated here):

✓ The AUDIT DOCS fixed-format report was printed, ending in `Decision: PASS | FAIL`
✓ No doc was rewritten without explicit --fix / user go-ahead

Missing reference → STOP. 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 — keyed on the carrier, like check 11.**

• **lane-era** — `bunx @gtrabanco/agentic-workflow@<pin> phase-lint <unit-doc>` (owner

`skills/phase-contract/SKILL.md`) must print `verdict PASS`, and `bunx @gtrabanco/agentic-workflow@<pin> ceremony docs check-phase-labels --slug <slug>` must answer `valid: true`. A `S#` hit in a lane-era doc is not a phase label: since #308 `S#` is the requirement id.

• **legacy carriers only** — `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; a hit quoting only the required `Step 0 — Discover the project` section is no phase label, and no count is restated here — the checker's own output enumerates them. 11. **Per-phase doc discipline — keyed on the unit's own carrier.** Pick the carrier mechanically, never by guess: `TASKS.md` in the unit folder means legacy carriage; its absence means the unit doc's `## Tasks`/`## Log`.

• **lane-era** — `bunx @gtrabanco/agentic-workflow@<pin> ceremony docs check-tasks-ticks --slug <slug>`

and `bunx @gtrabanco/agentic-workflow@<pin> ceremony docs check-progress-entry --slug <slug>` must both report `valid: true`: every `- [x] P<n>` has its `P<n>` line in `## Log`, and no task lacks one. Cite those two fields, never `check-all` (its `commit-format`/`docs-language` fields are checks 14 and 7). A doc with no `## Tasks` section answers `n/a` (`no ## Tasks section — legacy carrier`), so th