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.py is 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/ or manual/)
• 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:

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.

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:

1. Accuracy — Do docs match current code?
2. Completeness — Are all public interfaces covered?
3. Organization — Does folder structure match the prescribed layout?
4. Cross-references — Are all internal links valid?
5. Consistency — Tone, formatting, heading levels
6. 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/ and manual/ — link instead
• Do not move user-facing docs into docs/ or developer docs into manual/