Menu
Run a multi-stage parallel documentation audit with 18 specialized agents
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Based on SOC occupation classification
| name | audit-documentation |
| description | Run a multi-stage parallel documentation audit with 18 specialized agents |
| supports_parallel | true |
| fallback_available | true |
| estimated_time_parallel | 20 min |
| estimated_time_sequential | 90 min |
/audit-documentation| Condition | Mode | Time |
|---|---|---|
| Task tool available | Parallel | ~20 min |
| Task tool unavailable | Sequential | ~90 min |
| Context low (<20% remaining) | Sequential | ~90 min |
6-stage parallel audit analyzing documentation quality, accuracy, and lifecycle. Each stage produces JSONL output for synthesis.
Total Agents: 18 across 5 stages + 1 synthesis stage Output:
docs/audits/single-session/documentation/audit-[YYYY-MM-DD]/
Agent prompts and templates: See prompts.md for all agent prompt text, JSONL schemas, and report templates.
docs/technical-debt/FALSE_POSITIVES.jsonldocs/audits/single-session/documentation/mkdir -p "$AUDIT_DIR"npm run review:checkDependencies: 1A, 1B, 1C are fully independent. Stage 2 depends on 1C's link graph.
| Agent | Task | Output |
|---|---|---|
| 1A | Document inventory | stage-1-inventory.md |
| 1B | Baseline metrics | stage-1-baselines.md |
| 1C | Link extraction | stage-1-links.json |
Completion: Verify all 3 files exist and are non-empty.
| Agent | Task | Output |
|---|---|---|
| 2A | Internal link checker | stage-2-internal-links.jsonl |
| 2B | External URL checker | stage-2-external-links.jsonl |
| 2C | Cross-reference valid. | stage-2-cross-refs.jsonl |
| 2D | Orphan & connectivity | stage-2-orphans.jsonl |
Completion: Validate JSONL schemas:
node scripts/debt/validate-schema.js ${AUDIT_DIR}/stage-2-*.jsonl
| Agent | Task | Output |
|---|---|---|
| 3A | Accuracy checker | stage-3-accuracy.jsonl |
| 3B | Completeness checker | stage-3-completeness.jsonl |
| 3C | Coherence checker | stage-3-coherence.jsonl |
| 3D | Freshness checker | stage-3-freshness.jsonl |
| Agent | Task | Output |
|---|---|---|
| 4A | Markdown lint | stage-4-markdownlint.jsonl |
| 4B | Prettier compliance | stage-4-prettier.jsonl |
| 4C | Structure standards | stage-4-structure.jsonl |
5A, 5B, 5C run in parallel. 5D runs after 5B completes.
| Agent | Task | Output | Dep |
|---|---|---|---|
| 5A | Location validator | stage-5-location.jsonl | - |
| 5B | Archive candidates | stage-5-archive-candidates-raw.jsonl | - |
| 5C | Cleanup candidates | stage-5-cleanup-candidates.jsonl | - |
| 5D | Deep lifecycle | stage-5-lifecycle-analysis.jsonl | 5B |
cat ${AUDIT_DIR}/stage-2-*.jsonl ${AUDIT_DIR}/stage-3-*.jsonl \
${AUDIT_DIR}/stage-4-*.jsonl ${AUDIT_DIR}/stage-5-*.jsonl \
> ${AUDIT_DIR}/all-findings-raw.jsonl
Remove duplicates by file:line. Keep higher severity/confidence/evidence count.
Filter by file pattern, title pattern, expiration dates.
priority = (severityWeight * categoryMultiplier * confidenceWeight) / effortWeight
Weights: severity S0=100/S1=50/S2=20/S3=5, category links=1.5/accuracy=1.3/ freshness=1.0/format=0.8, confidence HIGH=1.0/MEDIUM=0.7/LOW=0.4, effort E0=1/E1=2/E2=4/E3=8.
Three queues: Immediate Fixes (S0/S1, E0/E1), Archive Queue, Delete/Merge Queue.
Output ${AUDIT_DIR}/FINAL_REPORT.md. See prompts.md for
template.
Before presenting findings, cross-reference against MASTER_DEBT.jsonl by file path, title similarity, root cause. Classify: Already Tracked (skip) | New (review) | Possibly Related (flag). Only New and Possibly Related proceed to Interactive Review.
Present in batches of 3-5 by severity. Each shows: title, severity, effort,
confidence, current state, suggested fix, acceptance tests, counter-argument,
recommendation. Track decisions in ${AUDIT_DIR}/REVIEW_DECISIONS.md. See
prompts.md for format.
node scripts/validate-audit.js ${AUDIT_DIR}/all-findings.jsonl
Check: required fields, no FALSE_POSITIVES matches, no duplicates, S0/S1 have HIGH/MEDIUM confidence.
npm run validate:canon (if CANON files updated)node scripts/reset-audit-triggers.js --type=single --category=documentation --applynode scripts/debt/intake-audit.js ${AUDIT_DIR}/all-findings.jsonl --source "audit-documentation-$(date +%Y-%m-%d)"| Stage | Category ID Prefix | TDMS Category |
|---|---|---|
| 2 - Links | DOC-LINK-* | documentation |
| 3 - Content | DOC-CONTENT-* | documentation |
| 4 - Format | DOC-FORMAT-* | documentation |
| 5 - Lifecycle | DOC-LIFECYCLE-* | documentation |
If interrupted: check .claude/state/audit-documentation-<date>.state.json. If
< 24h old, resume from last stage. If stale, start fresh. Preserve partial
findings in output directory.
State file tracks: audit_type, date, stage_completed,
partial_findings_path, last_updated.
Stage failures: Re-run specific agent. Empty output: Check for errors.
Context compaction: Re-read ${AUDIT_DIR}/ and resume.
| Version | Date | Description |
|---|---|---|
| 2.2 | 2026-02-24 | Trim to <500 lines: extract prompts to prompts.md |
| 2.1 | 2026-02-23 | Add mandatory MASTER_DEBT cross-reference step |
| 2.0 | 2026-02-02 | Complete rewrite: 6-stage parallel audit with 18 agents |
| 1.0 | 2025-xx-xx | Original single-session sequential audit |
Run a single-session AI optimization audit on the codebase
Run a single-session code review audit on the codebase
Run a single-session engineering productivity audit on the codebase
Run a comprehensive enhancement audit across the entire project - code, product, UX, content, workflows, infrastructure, external services, and meta-tooling.
Run a single-session performance audit on the codebase
Run a comprehensive multi-stage automation audit with parallel agents