Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.
/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
| # | 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
- 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."
- Check for staleness, not just existence. A README that exists but describes the wrong stack is worse than no README.
- 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.
- Auto-PASS for the ops repo itself. ApexYard's own docs are governed by its own process — this skill is for managed projects.
- Always persist via the lib. The persist step runs regardless of opt-in commit state.
- Severity vocabulary in the JSON is lowercase. The lib expects
critical/high/medium/low/info.
Part of ApexYard — multi-project SDLC framework for Claude Code · MIT.
1---2name: docs-audit3description: Diataxis docs audit — tutorials, how-to, reference, explanation; checks README, API docs, deployment guides, changelog, staleness.4disable-model-invocation: false5argument-hint: "[project-path]"6effort: medium7metadata:8 source: https://skillmd.com/skills/me2resh/docs-audit9---1011Writing: read docs/skills/shared/writing-rule.md before you write a durable artifact.1213# /docs-audit — Documentation Completeness (Diataxis)1415Deep-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.1617## Diataxis Framework1819| Quadrant | Purpose | What to look for |20|----------|---------|-----------------|21| **Tutorials** | Learning-oriented, guided first steps | Getting started guide, quickstart, "Hello World" |22| **How-to guides** | Goal-oriented, solving specific problems | Deployment guide, migration guide, troubleshooting |23| **Reference** | Information-oriented, accurate description | API docs, config reference, CLI flags, environment variables |24| **Explanation** | Understanding-oriented, why things work | Architecture overview, design decisions (AgDRs), ADRs |2526## Process2728### Step 1: README quality2930Check `README.md` for these sections (each is pass/fail):3132| Section | Present? | Quality check |33|---------|----------|--------------|34| Project description | | One paragraph explaining what this is and who it's for |35| Prerequisites | | Language version, tools needed, accounts required |36| Quick start | | Copy-pasteable commands to get running locally in < 5 minutes |37| Development setup | | How to set up the dev environment, run tests, lint |38| Deployment | | How to deploy to staging and production |39| Contributing | | How to contribute (branch naming, PR process, code standards) |40| License | | License type and link |4142### Step 2: API documentation (if applicable)4344- Check for OpenAPI / Swagger spec (`openapi.yaml`, `swagger.json`)45- Check for auto-generated docs (Swagger UI, Redoc, tsdoc, typedoc)46- Check if endpoints in the code match the spec (any undocumented endpoints?)47- Check for example requests and responses4849### Step 3: Operational docs5051- Deployment guide: how to deploy, what environment variables are needed52- Runbook: what to do when things go wrong (overlap with `/monitoring-audit`)53- Changelog: is there a CHANGELOG.md? Are releases documented?54- Architecture overview: high-level diagram or description of components55- AgDRs/ADRs: are technical decisions documented?5657### Step 4: Staleness detection5859- Compare `README.md` last-modified date with recent code changes60- Check if API docs mention endpoints/features that no longer exist61- Check if environment variable docs list vars that are no longer used62- Flag docs that reference deprecated tools, libraries, or patterns6364### Step 5: Output6566```67DOCS AUDIT — <project> @ <sha>6869Diataxis coverage:70 Tutorials: ✓ getting-started.md exists71 How-to: ✓ deployment guide, ✗ migration guide, ✗ troubleshooting72 Reference: ✓ OpenAPI spec (28 endpoints), ✗ env vars undocumented73 Explanation: ✓ 3 AgDRs, ✗ no architecture overview7475| # | Area | Status | Finding |76|----|------|--------|---------|77| D1 | README | WARN | Missing "Contributing" section |78| D2 | API docs | PASS | OpenAPI spec matches code (28/28 endpoints) |79| D3 | Env vars | FAIL | 12 env vars in .env.example, 0 documented in README |80| D4 | Changelog | PASS | CHANGELOG.md updated with last 5 releases |81| D5 | Staleness | WARN | README references "Express" but code migrated to Fastify 3 months ago |8283Documentation readiness: PARTIAL (1 fail, 2 warnings)84```8586## Persist the run + render trend8788After 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`.8990### Resolve project name + score + verdict9192`<project-name>` from `apexyard.projects.yaml` (or basename + `/handover` reminder if unregistered).9394Score: `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`.9596### Persist + render9798```bash99source "$(git rev-parse --show-toplevel)/.claude/hooks/_lib-audit-history.sh"100101# Lowercase severity in the payload — the lib expects critical/high/medium/low/info.102payload=$(mktemp); cat > "$payload" <<'EOF'103{104 "schema_version": 1,105 "findings": [106 {"id": "D2", "severity": "high", "status": "open", "summary": "No docs/how-to/ dir; recipes scattered in Slack"},107 {"id": "D3", "severity": "high", "status": "open", "summary": "Env vars not documented in README (12 in .env.example)"},108 {"id": "D5", "severity": "medium", "status": "open", "summary": "README references Express; code migrated to Fastify 3 months ago"}109 ]110}111EOF112113# Body: per templates/audits/docs-audit.md (Diataxis quadrants + README + staleness)114body=$(mktemp); cat > "$body" <<'EOF'115... (filled-in body — Diataxis groupings + README quality + staleness + Recommended priority) ...116EOF117118ts=$(date -u +"%Y-%m-%dT%H:%M:%SZ")119audit_run_persist "<project-name>" "docs-audit" "$ts" "fail" 60 "$body" < "$payload"120rm -f "$payload" "$body"121122audit_render_trend "<project-name>" "docs-audit" 5123```124125### Opt-in commit126127```bash128touch projects/<name>/audits/docs-audit/.audit-history-tracked129```130131## Rules1321331. **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."1342. **Check for staleness, not just existence.** A README that exists but describes the wrong stack is worse than no README.1353. **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.1364. **Auto-PASS for the ops repo itself.** ApexYard's own docs are governed by its own process — this skill is for managed projects.1375. **Always persist via the lib.** The persist step runs regardless of opt-in commit state.1386. **Severity vocabulary in the JSON is lowercase.** The lib expects `critical`/`high`/`medium`/`low`/`info`.139140---141142*Part of [ApexYard](https://github.com/me2resh/apexyard) — multi-project SDLC framework for Claude Code · MIT.*