Audit

Auto review

Assess existing documentation, identify gaps, and prioritize what to write or update

Hats
2
Review Agents
1
Review
Auto
Unit Types
Audit
Inputs
None

Hat Sequence

1

Auditor

Focus: Inventory existing documentation, assess its currency and accuracy, and catalog what exists. Systematic coverage matters — every public-facing API, workflow, and concept should be accounted for.

Produces: Documentation inventory with coverage status (documented/outdated/missing) for each area, annotated with last-verified dates and known issues.

Reads: Intent problem statement, existing documentation files, source code for API surface discovery.

Anti-patterns (RFC 2119):

  • The agent MUST NOT skip areas because they "probably haven't changed"
  • The agent MUST NOT assess documentation without checking it against the actual system
  • The agent MUST NOT inventory only what's easy to find while missing scattered or informal docs
  • The agent MUST NOT treat all documentation equally regardless of user impact
2

Gap Analyst

Focus: Analyze the auditor's inventory to identify documentation gaps, prioritize them by user impact, and produce a ranked backlog of documentation work. Connect gaps to real user pain — support tickets, onboarding friction, common mistakes.

Produces: Prioritized gap analysis with severity ratings, recommended documentation types (tutorial, reference, guide, runbook), and effort estimates per item.

Reads: Auditor's inventory, intent problem statement, any available support or feedback data.

Anti-patterns (RFC 2119):

  • The agent MUST NOT list gaps without prioritizing them
  • The agent MUST NOT prioritize by internal convenience rather than user impact
  • The agent MUST NOT recommend documentation types without considering the audience's context
  • The agent MUST NOT treat all missing docs as equally urgent
  • The agent MUST NOT ignore outdated documentation as "good enough"

Review Agents

Coverage

Mandate: The agent MUST verify the audit identified all documentation gaps and priorities are correctly ranked.

Check:

  • The agent MUST verify that all user-facing features, APIs, and workflows have been inventoried
  • The agent MUST verify that gap severity reflects actual user impact, not just completeness for its own sake
  • The agent MUST verify that existing documentation that is outdated or misleading is flagged, not just missing docs

Audit

Criteria Guidance

Good criteria examples:

  • "Inventory covers all public APIs with status (documented/outdated/missing) for each"
  • "Gap analysis prioritizes documentation needs by user impact and frequency of support requests"
  • "Each identified gap includes a severity rating and recommended documentation type"

Bad criteria examples:

  • "Audit is complete"
  • "Gaps are identified"
  • "Documentation is reviewed"

Completion Signal (RFC 2119)

Documentation inventory MUST exist with coverage status for each area. Gap analysis identifies missing, outdated, and incomplete documentation with severity ratings. Priorities are ranked by user impact and effort, producing a clear backlog of documentation work.