tools-only Execution Strategy
CRITICAL: Use plan mode and parallel agents for this audit.
Phase 1: Strategic Exploration (Plan Mode)
Use EnterPlanMode to research before generating findings. Launch up to 3 parallel Task agents with subagent_type=Explore:
Agent 1 - Documentation Inventory:
- Glob all .md files in the repo (not just /docs)
- Map documentation structure and folder hierarchy
- Check all internal links for validity
Agent 2 - Code Coverage Analysis:
- Identify all top-level modules/packages
- Check which have corresponding documentation
- Note undocumented public APIs and features
Agent 3 - Staleness Detection:
- Find references to removed/renamed files or modules
- Identify outdated patterns, old file paths
- Check for deprecated terminology or features
Phase 2: Synthesis
After agents return, synthesize findings in the plan file:
- Consolidate duplicate findings across agents
- Prioritize gaps by impact (onboarding, API consumers, operators)
- Identify structural reorganization opportunities
Phase 3: Report Generation
Exit plan mode and generate the final report using the synthesized findings.
Conduct an exhaustive audit of ALL Markdown documentation files in this repository. Use ultrathink extended thinking to thoroughly analyze every finding.
Scope: Leave No Stone Unturned.
- Scan EVERY .md file in the repository, not just /docs — check root-level files, nested READMEs in subdirectories, inline documentation in /examples, /scripts, etc.
- Cross-reference EVERY major module, service, and workflow in the codebase against existing documentation.
- Read each document in full; do not skim or sample.
Your Priorities (in order):
1. Structure & Organization Audit (Exhaustive): Map the complete documentation landscape:
- Catalog every .md file in the repo with its location and apparent purpose.
- Is there a clear entry point (README.md) that orients new readers?
- Is there a logical folder structure (e.g., /docs/guides, /docs/api, /docs/architecture)?
- Are documents at the right granularity (not everything in one mega-file, not fragmented into dozens of tiny files)?
- Is there an index or table of contents that provides navigation across ALL docs?
- Are related topics linked to each other, or do docs exist as isolated islands?
- Check every internal link — flag any that are broken or point to moved/renamed files.
2. Gap Analysis (Code vs. Docs) — Comprehensive Coverage: Systematically scan the actual codebase and verify documentation exists for:
- Every top-level module and package
- Every service, API route, or endpoint
- Every significant workflow or user-facing feature
- Every integration with external systems
- Every environment or deployment configuration
- Every non-obvious convention or pattern used repeatedly in the code
Do not assume documentation exists. Verify it. For each major code area, explicitly confirm: "Documentation exists at X" or "NO DOCUMENTATION FOUND."
3. Redundancy & Fragmentation (Full Inventory): Identify ALL documentation debt:
- Duplicate content explaining the same concept in multiple places (list every instance)
- Contradictory information across different files (quote the conflicts)
- Orphaned docs that are no longer linked from anywhere
- Stale sections that reference removed features, deprecated patterns, old file paths, or renamed modules
- Documents that have grown too long and should be split
- Empty or placeholder docs that were never filled in
4. Filter Noise (Abstraction Level): Ignore low-level implementation details (function parameters, variable names, specific class methods) unless they are critical to the overall system design. The documentation should explain the System, not replicate the Code.
5. Content Enrichment Requirements: For EVERY documentation gap identified, draft Markdown content that covers:
- The "Why": The business intent or architectural reasoning behind the module.
- The "How": High-level data flow, key relationships between services, and state management.
- The "Gotchas": Critical system-wide invariants, side effects (DB/Network), and non-obvious dependencies.
6. Audience & Discoverability (Complete Assessment): Assess whether docs serve ALL intended readers:
- Can a new developer onboard using only the docs? Walk through it step-by-step and note every gap.
- Can an external API consumer find what they need without reading internal architecture docs?
- Can an operator deploy, monitor, and troubleshoot using the docs?
- Are there missing doc types? Check for: quickstart, installation, configuration reference, troubleshooting, ADRs (architectural decision records), runbooks, changelog, contributing guide, API reference.
Output Format:
Part A — Complete Documentation Inventory:
Files Found: <total count>
<full tree view of ALL .md files in repo with line counts>
Broken Internal Links:
- <source file> → <broken link target> (line X)
- ...
Orphaned Files (not linked from anywhere):
- <file path>
- ...
Part B — Structural Recommendations:
Current Structure: <tree view of existing /docs and root-level .md files>
Proposed Structure:
/docs
├── index.md <- Central navigation hub
├── getting-started.md <- Onboarding quickstart
├── architecture/
│ ├── overview.md
│ └── ...
├── guides/
│ └── ...
└── api/
└── ...
Reorganization Actions:
- <MOVE: old/path.md → new/path.md — reason>
- <MERGE: file1.md + file2.md → combined.md — reason>
- <SPLIT: monolith.md → section1.md, section2.md — reason>
- <DELETE: orphaned-doc.md — reason>
- <CREATE: missing-doc.md — purpose and what it should cover>
Part C — Content Findings (Every Issue): Report EVERY finding, not just the most important ones:
Finding #<N>
Target File: <path to existing .md file> or <suggestion for new .md file>
Category: <Gap | Outdated | Redundant | Contradictory | Misplaced | Missing Links | Incomplete>
Severity: <Critical | Warning | Advisory>
The Discrepancy: <Detailed explanation of what the code does vs. what the docs say, or structural issue — include specific file paths, function names, or features involved>
Suggested Update (Markdown):
## <Section Title>
<Proposed documentation text that resolves the discrepancy>
Part D — Proposed Index: Generate a complete index.md (or update README.md) that serves as the documentation entry point with:
- Brief repo description
- Links to ALL doc sections with one-line descriptions
- "Start here" guidance for different audiences (new contributors, API consumers, operators)
- Quick reference to most critical docs
Part E — Summary Statistics:
Total .md files: X
Total gaps found: X
Total outdated sections: X
Total redundancies: X
Total broken links: X
Documentation coverage estimate: X% of major modules documented
Priority fixes (ranked by impact):
1. ...
2. ...
3. ...
Completeness Check: Before finalizing your report, verify:
- Every top-level directory in the codebase was checked for corresponding docs
- Every .md file in the repo was read and cataloged
- Every internal link was validated
- Every finding includes a concrete suggested fix, not just a description of the problem