docs-audit

/docs-audit — Documentation Completeness (Diataxis)

Deep-dive documentation analysis using the Diataxis framework. Checks that docs cover all four quadrants (tutorials, how-to guides, reference, explanation) and are not stale. Invoke when /launch-check's documentation row shows WARN or FAIL.

Diataxis Framework

Process

Step 1: README quality

Check README.md for these sections (each is pass/fail):

Step 2: API documentation (if applicable)

• Check for OpenAPI / Swagger spec (openapi.yaml, swagger.json)
• Check for auto-generated docs (Swagger UI, Redoc, tsdoc, typedoc)
• Check if endpoints in the code match the spec (any undocumented endpoints?)
• Check for example requests and responses

Step 3: Operational docs

• Deployment guide: how to deploy, what environment variables are needed
• Runbook: what to do when things go wrong (overlap with /monitoring-audit)
• Changelog: is there a CHANGELOG.md? Are releases documented?
• Architecture overview: high-level diagram or description of components
• AgDRs/ADRs: are technical decisions documented?

Step 4: Staleness detection

• Compare README.md last-modified date with recent code changes
• Check if API docs mention endpoints/features that no longer exist
• Check if environment variable docs list vars that are no longer used
• Flag docs that reference deprecated tools, libraries, or patterns

Step 5: Output

DOCS AUDIT — <project> @ <sha>

Diataxis coverage:
  Tutorials:   ✓ getting-started.md exists
  How-to:      ✓ deployment guide, ✗ migration guide, ✗ troubleshooting
  Reference:   ✓ OpenAPI spec (28 endpoints), ✗ env vars undocumented
  Explanation: ✓ 3 AgDRs, ✗ no architecture overview

| # | Area | Status | Finding |
|----|------|--------|---------|
| D1 | README | WARN | Missing "Contributing" section |
| D2 | API docs | PASS | OpenAPI spec matches code (28/28 endpoints) |
| D3 | Env vars | FAIL | 12 env vars in .env.example, 0 documented in README |
| D4 | Changelog | PASS | CHANGELOG.md updated with last 5 releases |
| D5 | Staleness | WARN | README references "Express" but code migrated to Fastify 3 months ago |

Documentation readiness: PARTIAL (1 fail, 2 warnings)

Persist the run + render trend

After printing the findings table, persist via the shared audit-history lib so the docs trend across runs becomes legible. See docs/agdr/AgDR-0019-audit-artefact-persistence.md.

Resolve project name + score + verdict

<project-name> from apexyard.projects.yaml (or basename + /handover reminder if unregistered).

Score: score = max(0, 100 - 25*critical - 10*high - 3*medium - 1*low). Verdict by worst-severity: critical/high → fail, medium → conditional, low/none → pass. Legacy "Documentation readiness" three-state: PARTIAL → conditional, MISSING → fail, COMPLETE → pass.

Persist + render

source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-audit-history.sh"

# Lowercase severity in the payload — the lib expects critical/high/medium/low/info.
payload=$(mktemp); cat > "$payload" <<'EOF'
{
  "schema_version": 1,
  "findings": [
    {"id": "D2", "severity": "high",   "status": "open", "summary": "No docs/how-to/ dir; recipes scattered in Slack"},
    {"id": "D3", "severity": "high",   "status": "open", "summary": "Env vars not documented in README (12 in .env.example)"},
    {"id": "D5", "severity": "medium", "status": "open", "summary": "README references Express; code migrated to Fastify 3 months ago"}
  ]
}
EOF

# Body: per templates/audits/docs-audit.md (Diataxis quadrants + README + staleness)
body=$(mktemp); cat > "$body" <<'EOF'
... (filled-in body — Diataxis groupings + README quality + staleness + Recommended priority) ...
EOF

ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
audit_run_persist "<project-name>" "docs-audit" "$ts" "fail" 60 "$body" < "$payload"
rm -f "$payload" "$body"

audit_render_trend "<project-name>" "docs-audit" 5

Opt-in commit

touch projects/<name>/audits/docs-audit/.audit-history-tracked

Rules

1. README is the minimum. Every project needs a README with at least: description, quick start, and how to deploy. Everything else is a "should have."
2. Check for staleness, not just existence. A README that exists but describes the wrong stack is worse than no README.
3. Diataxis is a lens, not a checklist. Don't fail a project for missing all four quadrants — most projects start with tutorials + reference and add the rest over time.
4. Auto-PASS for the ops repo itself. ApexYard's own docs are governed by its own process — this skill is for managed projects.
5. Always persist via the lib. The persist step runs regardless of opt-in commit state.
6. Severity vocabulary in the JSON is lowercase. The lib expects critical/high/medium/low/info.