doc-health-audit

Documentation Health Audit

Orchestrate a comprehensive documentation assessment across five dimensions. Each phase builds on the previous — structural issues are found before accuracy is checked, accuracy before completeness, and so on.

This skill does not duplicate any phase logic. It defines the run order, phase gating, and combined summary. Each phase delegates to its dedicated skill.

When to Use

• Pre-release audit — full pass before shipping
• Periodic health check — monthly or quarterly
• After a major refactor that touched many docs
• When documentation quality is unknown or untrusted
• First-time assessment of a doc set

For single-dimension checks, use the individual skills directly.

Pipeline

Phase 1: Structure     →  doc-maintenance
Phase 2: Accuracy      →  doc-claim-validator
Phase 3: Completeness  →  doc-completeness-audit
Phase 4: Quality       →  doc-quality-review
Phase 5: Architecture  →  doc-architecture-review

Why This Order

Each phase depends on the prior phase being reasonably healthy:

Phase	Depends on	Reason
Structure	—	Foundation. Broken links and orphans must be visible before anything else
Accuracy	Structure	Can't verify claims in docs you can't find or that have broken references
Completeness	Accuracy	No point inventorying gaps if existing docs contain false claims
Quality	Completeness	Review prose quality only on docs you intend to keep
Architecture	Completeness	Need to know what's missing before evaluating whether the structure can hold it

---

Execution

Step 1: Determine Scope

Before running phases, establish what to audit:

• Full audit — all documentation (docs/, site/, README.md)
• Scoped audit — specific directory or doc set (e.g., "just the reference section")
• Changed-only audit — docs modified since a git ref (git diff --name-only main...HEAD -- '*.md')

Pass the scope to each phase so they operate on the same set.