audit-docs

name	audit-docs
description	Use when asked to audit docs, review docs accuracy, or validate documentation claims against actual code, commands, APIs, configs, and diagrams.
metadata	{"short-description":"Verify every doc claim against the code"}

Docs Audit

Docs lie by going stale. Verify claims against code; never grade prose style.

1) Inventory claims

Walk each doc file and extract every checkable claim:

• Commands and flags (do they run? do the flags exist in the CLI source?)
• File paths and module names referenced (do they exist?)
• API/config examples (do the fields match the current types/schema?)
• Mermaid/architecture diagrams (does each node and edge correspond to a real module and a real dependency?)
• Version numbers, install instructions, env vars.

2) Verify

• Cheap checks first: paths via ls/glob, flags via --help or the arg-parser source, config fields via the schema/types.
• Runnable examples: actually run them in a scratch dir when safe; otherwise trace the code path and say "traced, not executed".
• Diagrams: grep imports to confirm each drawn edge; list edges that exist in code but are missing from the diagram (coverage), and drawn edges with no code counterpart (drift).

3) Report

Per file: ✅ verified / ❌ wrong (with the correct current value) / ⚠️ unverifiable (why).

• Lead with the wrong ones — those actively mislead.
• End with a coverage note: significant code areas (public commands, exported APIs) that no doc mentions.

Notes:

• Fixing is a separate pass — audit output must stay a faithful report, not a mixed diff.