Claude Cursor opencode Skill

audit-docs

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-conv

LLM Mart · 0 points · 4 views 191 listing impressions 0 install-command copies
Download gtrabanco-agentic-workflow-skills_audit-docs-88248cc.zip · 5 KB

Install

skills CLI npx skills add https://github.com/gtrabanco/agentic-workflow/tree/main/skills/audit-docs
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install gtrabanco-agentic-workflow@llmmart
Git git clone https://github.com/gtrabanco/agentic-workflow.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole gtrabanco/agentic-workflow collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

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.

  1. Phase naming — keyed on the carrier, like check 11.
    • lane-era — bun scripts/phase-lint.mjs <unit-doc> (owner skills/phase-contract/SKILL.md) must print verdict PASS, and bun scripts/ceremony.mjs 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. Today's 22 hits are all literal Step 0 — Discover the project citations; the grep is the legacy carrier's, so a lane-era S# is never read through it.
  2. 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 — bun scripts/ceremony.mjs docs check-tasks-ticks --slug <slug> and bun scripts/ceremony.mjs 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 the vacuous case routes to the legacy branch, never to a silent pass.
    • legacy — the original assertions on that unit's own files: completed phases ticked in TASKS.md, one progress.md entry per completed phase, the literal close-out tasks in the final phase.
    • Severity — a done unit whose ledger disagrees with its tasks: HIGH. The same on an in-progress unit: LOW (it may still be settling). Only high/low exist in this report's legend.
    • Close-out is audit-pr's contract (receipt + ordered gates): cite its verdict, never re-derive the retired literal tasks here.
  3. 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.
  4. Generated-docs provenance (only when the documentation map declares a Docs site block; otherwise state n/a). Scan the declared content dir for orphan pages each: (a) its source-unit exists in the roadmap or fix index — no match is an orphan (low: 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 ). Cite page path + unit per finding.
  5. 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).
  6. README currency against what shipped. Run each README against the tree: rg -n '<a retired name or stale claim>' README.md packages/*/README.md and every hit that names a surface the tree no longer carries (a retired skill in an install/uninstall example, a command count or package count the tree contradicts, a "none yet" beside shipped subcommands) is HIGH — the claim misleads a reader who acts on it. Its mirror: a shipped, consumer-facing surface with no README entry at all is HIGH (the document-or-don't-coin residue read at README scope — product-audit owns the product-wide sweep, this check is the docs-tree half). Superseded prose left standing beside its replacement is LOW. Owners: the rule is AGENTS.md §Working rules, the step is skills/unit-lane/references/DOCS.md.

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-15) | Finding | Sev | Evidence | Proposed fix |
    |---|-------------|---------|-----|----------|--------------|
    | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
    
    Checks run: <n>/15 (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. Only high and low are defined in this legend

  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: — no skill pins a tier; 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 unit-lane (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 → /unit-lane --fix <n>
      · already clean → nothing to do
    
Files (agentic-workflow)
  • SKILL.md 10.7 KB
    ---
    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 — 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
    
    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 — keyed on the carrier, like check 11.**
        - **lane-era** — `bun scripts/phase-lint.mjs <unit-doc>` (owner
          `skills/phase-contract/SKILL.md`) must print `verdict PASS`, and
          `bun scripts/ceremony.mjs 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. Today's 22 hits
          are all literal `Step 0 — Discover the project` citations; the grep is the
          legacy carrier's, so a lane-era `S#` is never read through it.
    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** — `bun scripts/ceremony.mjs docs check-tasks-ticks --slug <slug>`
          and `bun scripts/ceremony.mjs 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 the vacuous case routes to the legacy branch, never to a
          silent pass.
        - **legacy** — the original assertions on that unit's own files: completed
          phases ticked in `TASKS.md`, one `progress.md` entry per completed phase,
          the literal close-out tasks in the final phase.
        - **Severity** — a `done` unit whose ledger disagrees with its tasks: HIGH.
          The same on an `in-progress` unit: LOW (it may still be settling). Only
          `high`/`low` exist in this report's legend.
        - **Close-out** is `audit-pr`'s contract (receipt + ordered gates): cite its
          verdict, never re-derive the retired literal tasks here.
    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 orphan pages
        each: (a) its `source-unit` exists in the roadmap or fix index — no match
        is an **orphan** (low: 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
    ). 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).
    15. **README currency against what shipped.** Run each README against the
        tree: `rg -n '<a retired name or stale claim>' README.md packages/*/README.md`
        and every hit that names a surface the tree no longer carries (a retired
        skill in an install/uninstall example, a command count or package count the
        tree contradicts, a "none yet" beside shipped subcommands) is **HIGH** —
        the claim misleads a reader who acts on it. Its mirror: a shipped,
        consumer-facing surface with no README entry at all is **HIGH** (the
        document-or-don't-coin residue read at README scope — `product-audit` owns
        the product-wide sweep, this check is the docs-tree half). Superseded prose
        left standing beside its replacement is **LOW**. Owners: the rule is
        `AGENTS.md` §Working rules, the step is `skills/unit-lane/references/DOCS.md`.
    
    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-15) | Finding | Sev | Evidence | Proposed fix |
       |---|-------------|---------|-----|----------|--------------|
       | 1 | <which>     | <what>  | high|low | <path:line / #issue> | <smallest action> |
    
       Checks run: <n>/15 (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.
       Only `high` and `low` are defined in this legend
    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:`** — no skill pins a tier; 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 `unit-lane` (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 → /unit-lane --fix <n>
        · already clean → nothing to do
      ```
    

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.