audit-docs

Documentation Audit Skill

Audit all documentation sources for drift, staleness, and inconsistency against actual codebase behavior.

When to Use

• User says "audit docs", "check documentation", "docs audit", "documentation review", "docs drift", "stale docs"

Critical Constraints

NEVER:

• Modify any source files
• Update an existing report — always generate a new one
• Compare doc-to-doc without first grounding claims in actual code behavior
• Run subagents in the background (run_in_background: true is prohibited)

ALWAYS:

• Ground every cross-reference finding in what the code actually does (not what other docs say)
• Use subagents for parallel exploration
• Write report to {{AUTOSKILLIT_TEMP}}/audit-docs/docs_audit_{YYYY-MM-DD_HHMMSS}.md
• Provide file:line references for every finding
• Categorize findings by severity (CRITICAL, HIGH, MEDIUM, LOW)
• Produce a usable report even when one or more subagents fail

---

Documentation Sources

Enumerate and audit all of the following:

• CLAUDE.md — project instructions, architecture tree, file path references, tool/skill counts, layer descriptions
• docs/architecture/**/*.md — component names, module paths, layer assignments
• docs/requirements/**/*.md and docs/specs/**/*.md — API surface, behavioral contracts
• All README.md files at any depth in the repository
• Module/class/function docstrings in Python files under src/
• Recipe YAML description, summary, and note fields in .autoskillit/recipes/ and src/autoskillit/recipes/

---

Inconsistency Categories

Flag findings in these categories (maps to REQ-SKILL-004):

• Stale claims — doc asserts X, actual code behavior is Y
• Orphaned references — doc mentions a file, module, tool, class, or skill that no longer exists
• Missing docs — new subsystem or module with no mention in CLAUDE.md tree or arch docs
• Path/name drift — hyphen-vs-underscore mismatches, renamed symbols, old module paths
• Count mismatches — CLAUDE.md states N tools/skills/hooks but actual count differs
• Inter-doc contradictions — CLAUDE.md says A, arch doc says B about the same entity