Documentation Maintenance
Systematically audit, organize, and remediate project documentation by comparing the codebase against existing docs to find staleness, gaps, and misorganization.
When to Trigger
- After merging a feature branch or completing a refactor
- After dependency upgrades or API changes
- When onboarding surfaces confusion about project docs
- Periodic maintenance (monthly or per-release)
- When
scripts/doc_audit.pyis run manually and reports findings
Workflow Overview
Phase 1: Audit → Run deterministic scan + haiku search agents
Phase 2: Triage → Classify findings by severity and action type
Phase 3: Remediate → Dispatch specialized agents to fix/create docs
Phase 4: Quality → docs-architect reviews all changes
Phase 1: Audit
Step 1a — Run the deterministic scan
Execute the bundled audit script to get a baseline report:
python3 skills/doc-maintenance/scripts/doc_audit.py
The script produces a structured report covering:
- Broken internal links (markdown
[text](path)pointing to missing files) - Orphan docs (files not linked from any other doc or README)
- Missing required structure (expected folders/files absent from
docs/ormanual/) - Stale timestamp indicators (files unchanged for >90 days with code siblings that changed)
- Empty or stub files (< 3 lines of content)
Pass --json for machine-readable output. Pass --root PATH to override project root detection.
Step 1b — Dispatch haiku search agents
After the deterministic scan, launch parallel haiku subagents to perform deeper analysis.
Use model: "haiku" on all Task calls in this phase to minimize cost.
See references/agent-dispatch.md for full prompt templates.
Agent 1 — Code-to-doc coverage scan (subagent_type: "Explore", model: "haiku"):
Search the codebase for public APIs, CLI commands, config schemas, and exported modules.
Cross-reference against existing docs. Report anything undocumented.
Agent 2 — Doc-to-code freshness scan (subagent_type: "Explore", model: "haiku"):
Read each doc file and verify the code constructs it references still exist and match
current signatures/behavior. Report mismatches.
Agent 3 — Structure compliance scan (subagent_type: "Explore", model: "haiku"):
Compare current docs/ and manual/ layout against the prescribed folder structure
in references/folder-structure.md. Report missing folders, misplaced files, naming violations.
Agent 4 — Diagram opportunity scan (subagent_type: "Explore", model: "haiku"):
Scan all markdown files for ASCII/text diagrams (box-drawing characters, arrow notation,
indented tree structures beyond a few simple nodes) that should be converted to Mermaid.
Also identify sections describing flows, architectures, state machines, sequences, or
relationships where a diagram would add clarity but none exists. Report the file path,
line range, diagram type (flowchart, sequence, state, ER, etc.), and whether it is a
conversion or a net-new diagram.
Launch all four agents in parallel.
Step 1c — Merge results
Combine the script output with agent findings into a single audit report. Deduplicate overlapping findings. The report becomes the input for Phase 2.
Phase 2: Triage
Classify each finding into one of these action categories:
| Category | Description | Example |
|----------|-------------|---------|
| stale | Doc exists but references outdated code/behavior | CLI flag renamed but docs show old name |
| missing | No doc exists for a documented-worthy item | Public API endpoint with no reference doc |
| orphan | Doc exists but is unreachable / unlinked | Guide file not in any index or nav |
| misplaced | Doc exists but is in the wrong folder | Tutorial sitting in docs/architecture/ |
| irrelevant | Doc covers removed functionality | Guide for a deleted feature |
| structural | Folder structure deviates from prescribed layout | Missing docs/security/ folder |
| diagram-convert | ASCII/text diagram should be Mermaid | Complex box-drawing flowchart in architecture doc |
| diagram-missing | Section would benefit from a diagram | Multi-step process described only in prose |
Assign severity:
- P0 — User-facing doc is factually wrong (manual/)
- P1 — Developer doc references nonexistent code
- P2 — Missing doc for public API or feature
- P3 — Structural / organizational issues
- P4 — Minor staleness, cosmetic
Phase 3: Remediate
Route each finding to the appropriate specialist agent. Use the Task tool with
the subagent types listed below. See references/agent-dispatch.md for detailed
prompt templates.
| Doc type | Subagent type | Target location |
|----------|---------------|-----------------|
| API reference docs | reference-builder | docs/reference/ or docs/api/ |
| Architecture docs | technical-writer | docs/architecture/ |
| Developer guides (style, local dev, workflows) | technical-writer | docs/development/ |
| Testing docs | technical-writer | docs/testing/ |
| Security docs | technical-writer | docs/security/ |
| User-facing tutorials | learning-guide | manual/tutorials/ |
| User-facing how-to guides | learning-guide | manual/guides/ |
| User-facing getting started | learning-guide | manual/getting-started/ |
| Plans and proposals | technical-writer | docs/plans/ |
| ASCII diagram conversion | mermaid-expert | Inline in existing doc |
| New diagrams for prose sections | mermaid-expert | Inline in existing doc |
Parallel dispatch: Group independent remediation tasks and dispatch them simultaneously. Only serialize when one doc depends on another (e.g., an API reference needed before a tutorial that links to it). Dispatch up to 4 remediation agents in parallel per batch.
For updates to existing docs: Provide the agent with the current file contents and the specific finding to fix. Instruct it to make minimal, targeted edits.
For new docs: Provide the agent with the relevant source code, the target file path, and the folder-structure spec so it follows naming conventions.
Phase 4: Quality Gate
After all remediation agents complete, dispatch a single docs-architect agent to review
the full set of changes. The quality gate checks:
- Accuracy — Do docs match current code?
- Completeness — Are all public interfaces covered?
- Organization — Does folder structure match the prescribed layout?
- Cross-references — Are all internal links valid?
- Consistency — Tone, formatting, heading levels
- No orphans — Every new doc is linked from an index or parent doc
If the quality gate fails, loop back to Phase 3 for the specific issues flagged. Maximum 2 remediation loops before escalating to the user.
Folder Structure
The prescribed folder layout is defined in references/folder-structure.md. Summary:
docs/ — Internal / developer documentation
docs/
├── architecture/ — System design, ADRs, component diagrams
├── development/ — Developer guides: style, local setup, issue tracking
├── plans/ — Proposals, RFCs, roadmaps
├── reviews/ — Code review records, audit reports
├── testing/ — Test strategy, coverage reports, test plans
├── reports/ — Generated reports, metrics, analysis
├── security/ — Security policies, threat models, audit findings
├── api/ — Internal API docs (OpenAPI specs, gRPC protos)
├── reference/ — CLI reference, config reference, manpages
├── ideas/ — Exploratory notes, spikes, brainstorms
└── archive/ — Deprecated docs preserved for history
manual/ — User-facing documentation (project root)
manual/
├── getting-started/ — Installation, quickstart, first steps
├── guides/ — How-to guides for common tasks
├── tutorials/ — Step-by-step learning paths
├── reference/ — User-facing command/config reference
└── troubleshooting/ — FAQ, common errors, known issues
README.md — Project root
The main README is audited for accuracy but not reorganized. Findings about the README are reported as stale/missing items for manual remediation.
Anti-Patterns
- Do not delete docs without confirming the feature they describe is truly removed
- Do not reorganize docs without updating all internal cross-references
- Do not create stub files just to fill the folder structure — only create docs with real content
- Do not duplicate content between
docs/andmanual/— link instead - Do not move user-facing docs into
docs/or developer docs intomanual/