Audit

Auto review

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

Hats
2
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:

  • Skipping areas because they "probably haven't changed"
  • Assessing documentation without checking it against the actual system
  • Inventorying only what's easy to find while missing scattered or informal docs
  • Treating 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:

  • Listing gaps without prioritizing them
  • Prioritizing by internal convenience rather than user impact
  • Recommending documentation types without considering the audience's context
  • Treating all missing docs as equally urgent
  • Ignoring outdated documentation as "good enough"

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

Documentation inventory exists 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.