Menu
Scan all docs, auto-fix formatting/headers/links, report issues as JSONL, and generate enhancement recommendations
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
Structured discovery-first planning for complex tasks. Ask exhaustive categorized questions, build a standalone decision record, then produce a step-by-step implementation plan with audit checkpoints and convergence-loop verification of diagnosis and plan claims for user approval before any code is written.
Multi-agent research engine that decomposes questions, dispatches parallel searcher agents, synthesizes findings with citations and confidence levels, runs mandatory contrarian/OTB challenges, gap-pursuit verification, and cross-model verification via Gemini CLI, and produces structured output with downstream adapters, research index, and management commands.
Pre-flight checklist for work sessions — loads context, runs health scripts, surfaces warnings, and gates on acknowledgment before work begins.
PR Review Retrospective -- actionable analysis of a PR's review cycle with convergence-loop deliverable verification, interactive findings walkthrough, and dashboard for missing retros
Process external PR code review feedback (CodeRabbit, Qodo, SonarCloud, Gemini) through a structured 8-step protocol. Parses all items, categorizes by severity and origin, fixes in priority order, tracks deferred items to TDMS, and captures learnings. This skill processes review feedback — it does not generate reviews.
Query the Content Analysis System (CAS) knowledge base. Search extraction candidates, filter by tags/type/source, search across all analyzed sources.
| name | doc-optimizer |
| description | Scan all docs, auto-fix formatting/headers/links, report issues as JSONL, and generate enhancement recommendations |
| supports_parallel | true |
| fallback_available | false |
| estimated_time_parallel | 40 min |
| estimated_time_sequential | 120 min |
Version: 1.5 Last Updated: 2026-04-03 Status: ACTIVE Waves: 5
waves with 13 agents Output: .claude/state/doc-optimizer/
What This Does: Wave-based orchestrator that deploys 13 parallel agents across 5 waves to analyze, auto-fix, report, and recommend improvements for every non-archived document in the repository.
Differentiator from /audit-documentation: That skill is a read-only
diagnostic (18 agents, report-only). This skill is a repair + enhancement
tool -- it auto-fixes formatting/headers/links, reports issues as JSONL, AND
generates actionable improvement recommendations.
/doc-optimizerWave 0: Discovery (Orchestrator, sequential)
Build file inventory, link graph, metadata index
~2 min
Wave 1: Independent Analysis (3 parallel + 1 sequential)
1A: Format & Lint Fixer (AUTO-FIX)
1C: External Link Validator (REPORT)
1D: Content Accuracy Checker (MIXED)
1B: Header & Metadata Fixer (AUTO-FIX) <- sequential after 1A
~8-12 min
Wave 2: Graph-Dependent Analysis (4 parallel)
2A: Internal Link Fixer (MIXED)
2B: Orphan & Connectivity (REPORT)
2C: Freshness & Lifecycle (REPORT)
2D: Cross-Ref & Deps (REPORT)
~8-12 min
Wave 3: Issue Synthesis (2 parallel)
3A: Coherence & Duplication (REPORT)
3B: Structure & Classification (REPORT)
~5 min
Wave 4: Enhancement & Optimization (3 parallel)
4A: Quality & Readability Scorer (REPORT)
4B: Content Gap & Consolidation (REPORT)
4C: Visual & Navigation Enhancer (REPORT)
~8-12 min
Orchestrator: Unify -> Dedupe -> Report -> TDMS intake
~5 min
Post-Run: Cleanup
Delete temp files (.claude/state/doc-optimizer/)
Identify & remove obsolete audit/review artifacts from docs/
~2 min
Read
.claude/skills/doc-optimizer/prompts.mdfor full agent prompt specifications.
| ID | Name | Type | Wave | Mode |
|---|---|---|---|---|
| 1A | Format & Lint Fixer | AUTO-FIX | 1 | parallel |
| 1B | Header & Metadata Fixer | AUTO-FIX | 1 | after 1A |
| 1C | External Link Validator | REPORT | 1 | parallel |
| 1D | Content Accuracy Checker | MIXED | 1 | parallel |
| 2A | Internal Link Fixer | MIXED | 2 | parallel |
| 2B | Orphan & Connectivity | REPORT | 2 | parallel |
| 2C | Freshness & Lifecycle | REPORT | 2 | parallel |
| 2D | Cross-Ref & Dependency | REPORT | 2 | parallel |
| 3A | Coherence & Duplication | REPORT | 3 | parallel |
| 3B | Structure & Classification | REPORT | 3 | parallel |
| 4A | Quality & Readability | REPORT | 4 | parallel |
| 4B | Content Gap & Consolidation | REPORT | 4 | parallel |
| 4C | Visual & Navigation | REPORT | 4 | parallel |
[!CRITICAL] The previous run crashed because 8 agents returned full results to the orchestrator, overflowing the context window. These rules are mandatory.
Every agent prompt MUST end with this instruction (append to all prompts):
CRITICAL RETURN PROTOCOL: When you finish, return ONLY this single line:
COMPLETE: [agent-id] wrote N findings to [output-path]
Do NOT include finding details, file listings, summaries, or analysis in your
return message. All details belong in the JSONL output file, not your response.
The orchestrator checks agent completion via file existence and line count only:
# CORRECT - check file exists and count lines
wc -l < ".claude/state/doc-optimizer/wave1-format.jsonl" 2>/dev/null || echo "0"
# WRONG - never do this in orchestrator context
# cat .claude/state/doc-optimizer/wave1-format.jsonl
If wc -l returns 0 for any output file, this is likely the Windows agent
output bug (anthropics/claude-code#39791). Check the task-notification result
for that agent -- if it contains findings, write them to the file. If no
findings available via any channel, report the failure to the user.
If context is running low (past ~60% usage), stop after the current wave,
save progress, and resume in a new invocation. The progress.json file tracks
exactly where to resume.
Recommended chunking: Wave 0+1 -> pause -> Wave 2 -> pause -> Wave 3+4 -> unify.
shared-state.json inventory entries should include ONLY: path, size_bytes,
word_count. Strip version, last_updated, status fields to reduce file
size. Agents that need metadata should extract it themselves from individual
files.
Before launching each wave, the orchestrator should estimate remaining context. If the conversation already contains 3+ agent completions, consider saving state and resuming in a new session rather than risking overflow.
Background agent output files may be 0 bytes on Windows
(anthropics/claude-code#39791). After each wave completes, check each agent's
JSONL output file size. If 0 bytes, capture the task-notification <result>
text and write it to the expected JSONL file using the Write tool. Do NOT
proceed to the next wave until all current wave output files are non-empty.
Empty results must never be silently accepted.
Standard schema from docs/templates/JSONL_SCHEMA_STANDARD.md plus these
additional fields:
{
"category": "string",
"title": "string",
"fingerprint": "string (<category>::<file>::<id>)",
"severity": "S0|S1|S2|S3",
"effort": "E0|E1|E2|E3",
"confidence": "number (0-100)",
"files": ["array of file paths"],
"why_it_matters": "string",
"suggested_fix": "string",
"acceptance_tests": ["array"],
"evidence": ["array (optional)"],
"auto_fixed": "boolean -- whether agent already applied the fix",
"agent": "string -- which agent produced finding (1A, 1B, etc.)",
"wave": "number -- which wave (0-4)",
"finding_type": "issue|enhancement -- distinguishes problems from improvement ideas"
}
.claude/state/doc-optimizer/
shared-state.json # Wave 0: inventory, link graph, metadata
wave1-format.jsonl # Agent 1A findings
wave1-headers.jsonl # Agent 1B findings
wave1-external-links.jsonl # Agent 1C findings
wave1-accuracy.jsonl # Agent 1D findings
wave2-internal-links.jsonl # Agent 2A findings
wave2-orphans.jsonl # Agent 2B findings
wave2-lifecycle.jsonl # Agent 2C findings
wave2-crossrefs.jsonl # Agent 2D findings
wave3-coherence.jsonl # Agent 3A findings
wave3-structure.jsonl # Agent 3B findings
wave4-quality.jsonl # Agent 4A findings
wave4-gaps.jsonl # Agent 4B findings
wave4-navigation.jsonl # Agent 4C findings
all-findings.jsonl # Unified + deduped
progress.json # Wave/agent progress tracker
SUMMARY_REPORT.md # Final human-readable report
# Create output directory
mkdir -p .claude/state/doc-optimizer
# Verify output directory is safe
STATE_DIR=".claude/state/doc-optimizer"
STATE_PATH=$(realpath "${STATE_DIR}" 2>/dev/null || echo "${STATE_DIR}")
if [ -z "${STATE_DIR}" ] || [ "${STATE_PATH}" = "/" ] || [[ "${STATE_DIR}" == ".."* ]]; then
echo "FATAL: Invalid or unsafe STATE_DIR"
exit 1
fi
Initialize progress.json:
{
"started": "<ISO datetime>",
"lastUpdated": "<ISO datetime>",
"waves": {
"0": { "status": "pending" },
"1": {
"status": "pending",
"agents": {
"1A": "pending",
"1B": "pending",
"1C": "pending",
"1D": "pending"
}
},
"2": {
"status": "pending",
"agents": {
"2A": "pending",
"2B": "pending",
"2C": "pending",
"2D": "pending"
}
},
"3": {
"status": "pending",
"agents": { "3A": "pending", "3B": "pending" }
},
"4": {
"status": "pending",
"agents": { "4A": "pending", "4B": "pending", "4C": "pending" }
}
},
"unification": { "status": "pending" },
"report": { "status": "pending" }
}
Load false positives if they exist:
if [ -f "docs/audits/FALSE_POSITIVES.jsonl" ]; then
echo "Loaded false positives database"
else
echo "No false positives database found (proceeding without filter)"
fi
Build the shared state that all subsequent waves depend on. This runs in the orchestrator context (not a subagent).
2.1: Build File Inventory -- Glob all active .md files, exclude node_modules, .git, docs/archive. For each, extract: path, size (bytes), word count.
2.2: Extract Link Graph -- For each .md file, extract internal links, external URLs, and anchor refs with source file and line number.
2.3: Extract Metadata -- For each .md file, parse version, lastUpdated, tier, status from frontmatter or inline headers.
2.4: Write shared-state.json -- Inventory + link graph + metadata. Update
progress.json: Wave 0 = "completed".
Launch 1A + 1C + 1D in parallel (3 agents), then 1B sequentially after 1A.
Read
.claude/skills/doc-optimizer/prompts.md-- Wave 1 section for agent prompts.
Wave 1 Checkpoint -- verify all 4 output files exist. Update progress.json.
Launch 2A + 2B + 2C + 2D in parallel (4 agents). All receive shared-state.json.
Read
.claude/skills/doc-optimizer/prompts.md-- Wave 2 section for agent prompts.
Wave 2 Checkpoint -- verify all 4 output files exist. Update progress.json.
Launch 3A + 3B in parallel (2 agents).
Read
.claude/skills/doc-optimizer/prompts.md-- Wave 3 section for agent prompts.
Wave 3 Checkpoint -- verify both output files exist. Update progress.json.
Launch 4A + 4B + 4C in parallel (3 agents). Each receives shared-state.json plus awareness of Wave 1-3 finding counts.
Read
.claude/skills/doc-optimizer/prompts.md-- Wave 4 section for agent prompts.
Wave 4 Checkpoint -- verify all 3 output files exist. Update progress.json.
Concatenate all 13 JSONL files, deduplicate by fingerprint (keep highest
severity), filter against FALSE_POSITIVES.jsonl, sort by finding_type >
severity > effort > files. Write to all-findings.jsonl.
Generate SUMMARY_REPORT.md with: executive summary, severity breakdown,
auto-fixes applied, top 20 issues, top 20 enhancements, per-wave breakdown,
bottom-20 quality scores, content gap analysis, navigation recommendations.
# Dry run first
node scripts/debt/intake-audit.js .claude/state/doc-optimizer/all-findings.jsonl --source "doc-optimizer-$(date +%Y-%m-%d)" --dry-run
# Real intake (after user approval)
node scripts/debt/intake-audit.js .claude/state/doc-optimizer/all-findings.jsonl --source "doc-optimizer-$(date +%Y-%m-%d)"
# CRITICAL: prevent generate-views.js from overwriting intake results
cp docs/technical-debt/MASTER_DEBT.jsonl docs/technical-debt/raw/deduped.jsonl
npm run docs:indexrm -rf .claude/state/doc-optimizer/Do NOT remove: docs/technical-debt/, docs/archive/completed-plans/,
docs/templates/, docs/agent_docs/, docs/decisions/
If context compacts mid-run, read progress.json to determine current state:
| Progress State | Resume Action |
|---|---|
| Wave 0 pending | Start from beginning |
| Wave 0 complete, Wave 1 pending | Run Wave 1 |
| Wave 1 complete, Wave 2 pending | Run Wave 2 |
| Wave 2 complete, Wave 3 pending | Run Wave 3 |
| Wave 3 complete, Wave 4 pending | Run Wave 4 |
| Wave 4 complete, unification pending | Run Step 7 |
| Unification complete, report pending | Run Step 8 |
cat .claude/state/doc-optimizer/progress.json 2>/dev/null
ls -1 .claude/state/doc-optimizer/wave*.jsonl 2>/dev/null | wc -l
ls -la .claude/state/doc-optimizer/shared-state.json 2>/dev/null
Resume from the last completed wave.
/doc-optimizer
No arguments needed. The skill scans all non-archived docs automatically.
/audit-documentation -- Read-only diagnostic audit (18 agents, report-only)/audit-comprehensive -- Full 7-domain audit including documentation/docs-maintain -- Quick document sync check| Script | Used By | Purpose |
|---|---|---|
scripts/check-doc-headers.js | Agent 1B | Header validation |
scripts/check-docs-light.js | Agent 1B | Light doc check |
scripts/check-external-links.js | Agent 1C | External URL validation |
scripts/check-content-accuracy.js | Agent 1D | Accuracy checks |
scripts/check-document-sync.js | Agent 2D | Template-instance sync |
scripts/check-cross-doc-deps.js | Agent 2D | Dependency rules |
scripts/check-doc-placement.js | Agent 2C | Placement/archival |
When modifying this skill, also update:
| Document | Section |
|---|---|
docs/SLASH_COMMANDS_REFERENCE.md | /doc-optimizer reference |
.claude/skills/SKILL_INDEX.md | Add doc-optimizer entry |
| Version | Date | Description |
|---|---|---|
| 1.5 | 2026-04-03 | Windows agent output fallback for 0-byte files (#39791) |
| 1.4 | 2026-02-24 | Extract 13 agent prompts to prompts.md (71% size reduction) |
| 1.3 | 2026-02-14 | Dedupe CRITICAL RETURN PROTOCOL (13x inline -> 1 shared ref) |
| 1.2 | 2026-02-07 | Step 10 expanded: temp file cleanup + obsolete artifact removal |
| 1.1 | 2026-02-07 | Context safety: return protocol, wave chunking, budget checks |
| 1.0 | 2026-02-07 | Initial version: 5-wave, 13-agent doc optimizer |