git:20260418.1afeb1d to git:20260518.4743f32

47 added, 0 removed. Audit A to A.

---

name: docs-audit

description: Documentation completeness audit using the Diataxis framework — tutorials, how-to guides, reference, explanation. Checks README quality, API docs, deployment guides, changelog, and staleness. Deep-dive companion to /launch-check's documentation dimension.

disable-model-invocation: false

argument-hint: "[project-path]"

effort: medium

---

# /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

| Quadrant | Purpose | What to look for |

|----------|---------|-----------------|

| **Tutorials** | Learning-oriented, guided first steps | Getting started guide, quickstart, "Hello World" |

| **How-to guides** | Goal-oriented, solving specific problems | Deployment guide, migration guide, troubleshooting |

| **Reference** | Information-oriented, accurate description | API docs, config reference, CLI flags, environment variables |

| **Explanation** | Understanding-oriented, why things work | Architecture overview, design decisions (AgDRs), ADRs |

## Process

### Step 1: README quality

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

| Section | Present? | Quality check |

|---------|----------|--------------|

| Project description | | One paragraph explaining what this is and who it's for |

| Prerequisites | | Language version, tools needed, accounts required |

| Quick start | | Copy-pasteable commands to get running locally in < 5 minutes |

| Development setup | | How to set up the dev environment, run tests, lint |

| Deployment | | How to deploy to staging and production |

| Contributing | | How to contribute (branch naming, PR process, code standards) |

| License | | License type and link |

### 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

|----|------|--------|---------|

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

+ ```bash

+ 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

+ ```bash

+ 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`.