audit

Audit — Documentation Quality & Consistency Review

Systematically review existing project documentation for quality, completeness, consistency with code, and internal coherence. Produce a prioritized findings report.

Core Principles

1. Evidence-based: Every finding must cite a specific file, section, or line — no vague complaints
2. Code-grounded: Cross-reference documentation claims against the actual codebase
3. Prioritized: Findings are classified by severity so the user can fix what matters first
4. Read-only by default: This skill only reads and reports — document modifications require explicit user opt-in (Step 8)
5. Honest: Report real issues, don't inflate findings to look thorough

Severity Levels

Severity	Meaning	Example
Critical	Documentation is wrong or dangerously misleading	API doc shows deleted endpoint, security guide has incorrect auth flow
Major	Significant gap or inconsistency that causes confusion	Feature doc missing for a core module, conflicting architecture descriptions
Minor	Quality issue that degrades usefulness but isn't blocking	Typos in API params, outdated version numbers, missing examples
Info	Observation or improvement suggestion	Better organization possible, diagram would help clarity

Workflow

Step 1: Determine Audit Scope

Parse the arguments to determine what to audit:

1. If a path argument is provided (e.g., /spec-forge:audit ../../other-project), use that as the project root
2. If no path, use the current working directory
3. Verify the target has documentation (check for docs/, README.md, or markdown files)

If no documentation found, inform the user and stop.

Use AskUserQuestion to ask:

• Audit focus: Full audit, or focus on a specific area? (Options: Full / API docs only / Feature docs only / Architecture docs only / Custom path)
• Code alignment: Should I cross-reference docs against the codebase? (Yes / No — skip if docs-only repo like aipartnerup-docs)