Octocode Documentation Writer

1---
2name: octocode-documentation-writer
3description: This skill should be used when the user asks to "generate documentation", "document this project", "create docs", "write documentation", "update documentation", "document all APIs", "generate onboarding docs", "create developer docs", or needs comprehensive codebase documentation. Orchestrates parallel AI agents to analyze code and produce documentation files.
4---
5 
6# Repository Documentation Generator
7 
8**Production-ready 6-phase pipeline with intelligent orchestration, research-first validation, and conflict-free file ownership.**
9 
10 
11<what>
12This command orchestrates specialized AI agents in 6 phases to analyze your code repository and generate comprehensive documentation:
13</what>
14 
15<steps>
16  <phase_1>
17  **Discovery+Analysis** (Phase 1)
18  Agent: Opus
19  Parallel: 4 parallel agents
20  What: Analyze language, architecture, flows, and APIs
21  Input: Repository path
22  Output: `analysis.json`
23  </phase_1>
24 
25  <phase_2>
26  **Engineer Questions** (Phase 2)
27  Agent: Opus
28  What: Generates comprehensive questions based on the analysis
29  Input: `analysis.json`
30  Output: `questions.json`
31  </phase_2>
32 
33  <phase_3>
34  **Research Agent** (Phase 3) 🆕
35  Agent: Sonnet
36  Parallel: Dynamic (based on question volume)
37  What: Deep-dive code forensics to ANSWER the questions with evidence
38  Input: `questions.json`
39  Output: `research.json`
40  </phase_3>
41 
42  <phase_4>
43  **Orchestrator** (Phase 4)
44  Agent: Opus
45  What: Groups questions by file target and assigns exclusive file ownership to writers
46  Input: `questions.json` + `research.json`
47  Output: `work-assignments.json` (file-based assignments for parallel writers)
48  </phase_4>
49 
50  <phase_5>
51  **Documentation Writers** (Phase 5)
52  Agent: Sonnet
53  Parallel: 1-8 parallel agents (dynamic based on workload)
54  What: Synthesize research and write comprehensive documentation with exclusive file ownership
55  Input: `analysis.json` + `questions.json` + `research.json` + `work-assignments.json`
56  Output: `documentation/*.md` (16 core docs, 5 required + supplementary files)
57  </phase_5>
58 
59  <phase_6>
60  **QA Validator** (Phase 6)
61  Agent: Sonnet
62  What: Validates documentation quality using LSP-powered verification
63  Input: `documentation/*.md` + `analysis.json` + `questions.json`
64  Output: `qa-results.json` + `QA-SUMMARY.md`
65  </phase_6>
66</steps>
67 
68<subagents>
69Use spawn explore opus/sonnet/haiku subagents to explore code with MCP tools (localSearchCode, lspGotoDefinition, lspCallHierarchy, lspFindReferences)
70</subagents>
71 
72**Documentation Flow:** analysis.json → questions.json → **research.json** → work-assignments.json → documentation (conflict-free!)
73 
74---
75 
76## ⚠️ CRITICAL: Parallel Agent Execution
77 
78<parallel_execution_critical importance="maximum">
79 
80**STOP. READ THIS TWICE.**
81 
82### 1. THE RULE
83**You MUST spawn parallel agents in a SINGLE message with multiple Task tool calls.**
84 
85### 2. FORBIDDEN BEHAVIOR
86**FORBIDDEN:** Calling `Task` sequentially (one per response).
87**REASON:** Sequential calls defeat parallelism and slow down execution by 4x-8x.
88 
89### 3. REQUIRED CONFIRMATION
90Before launching any parallel phase (1, 3, 5), you **MUST** verify:
91- [ ] All Task calls are prepared for a SINGLE response
92- [ ] No dependencies exist between these parallel agents
93- [ ] Each agent has exclusive scope (no file conflicts)
94 
95<correct_pattern title="✅ CORRECT: Single response launches all agents concurrently">
96```
97// In ONE assistant message, include ALL Task tool invocations:
98Task(description="Discovery 1A-language", subagent_type="general-purpose", prompt="...", model="opus")
99Task(description="Discovery 1B-components", subagent_type="general-purpose", prompt="...", model="opus")
100Task(description="Discovery 1C-dependencies", subagent_type="general-purpose", prompt="...", model="opus")
101Task(description="Discovery 1D-flows", subagent_type="general-purpose", prompt="...", model="opus")
102// ↑ All 4 execute SIMULTANEOUSLY
103```
104</correct_pattern>
105 
106<wrong_pattern title="❌ WRONG: Sequential calls lose parallelism">
107```
108// DON'T DO THIS - Each waits for previous to complete
109Message 1: Task(description="Discovery 1A") → wait for result
110Message 2: Task(description="Discovery 1B") → wait for result
111Message 3: Task(description="Discovery 1C") → wait for result
112Message 4: Task(description="Discovery 1D") → wait for result
113// ↑ 4x slower! No parallelism achieved
114```
115</wrong_pattern>
116 
117</parallel_execution_critical>
118 
119---
120 
121## Execution Flow Diagram
122 
123```mermaid
124flowchart TB
125    Start([/octocode-documentation-writer PATH]) --> Validate[Pre-Flight Validation]
126    Validate --> Init[Initialize Workspace]
127 
128    Init --> P1[Phase 1: Discovery+Analysis]
129 
130    subgraph P1_Parallel["🔄 RUN IN PARALLEL (4 agents)"]
131        P1A[Agent 1A:<br/>Language & Manifests]
132        P1B[Agent 1B:<br/>Components]
133        P1C[Agent 1C:<br/>Dependencies]
134        P1D[Agent 1D:<br/>Flows & APIs]
135    end
136 
137    P1 --> P1_Parallel
138    P1_Parallel --> P1Agg[Aggregation:<br/>Merge into analysis.json]
139    P1Agg --> P1Done[✅ analysis.json created]
140 
141    P1Done -->|Reads analysis.json| P2[Phase 2: Engineer Questions<br/>Single Agent - Opus]
142    P2 --> P2Done[✅ questions.json created]
143 
144    P2Done -->|Reads questions.json| P3[Phase 3: Research 🆕<br/>Parallel Agents - Sonnet]
145    
146    subgraph P3_Parallel["🔄 RUN IN PARALLEL"]
147       P3A[Researcher 1]
148       P3B[Researcher 2]
149       P3C[Researcher 3]
150    end
151    
152    P3 --> P3_Parallel
153    P3_Parallel --> P3Agg[Aggregation:<br/>Merge into research.json]
154    P3Agg --> P3Done[✅ research.json created<br/>Evidence-backed answers]
155 
156    P3Done -->|Reads questions + research| P4[Phase 4: Orchestrator<br/>Single Agent - Opus]
157    P4 --> P4Group[Group questions<br/>by file target]
158    P4 --> P4Assign[Assign file ownership<br/>to writers]
159    P4Assign --> P4Done[✅ work-assignments.json]
160 
161    P4Done --> P5[Phase 5: Documentation Writers]
162    P5 --> P5Input[📖 Input:<br/>work-assignments.json<br/>+ research.json]
163    P5Input --> P5Dist[Each writer gets<br/>exclusive file ownership]
164 
165    subgraph P5_Parallel["🔄 RUN IN PARALLEL (1-8 agents)"]
166        P5W1[Writer 1]
167        P5W2[Writer 2]
168        P5W3[Writer 3]
169        P5W4[Writer 4]
170    end
171 
172    P5Dist --> P5_Parallel
173    P5_Parallel --> P5Verify[Verify Structure]
174    P5Verify --> P5Done[✅ documentation/*.md created]
175 
176    P5Done --> P6[Phase 6: QA Validator<br/>Single Agent - Sonnet]
177    P6 --> P6Done[✅ qa-results.json +<br/>QA-SUMMARY.md]
178 
179    P6Done --> Complete([✅ Documentation Complete])
180 
181    style P1_Parallel fill:#e1f5ff
182    style P3_Parallel fill:#e1f5ff
183    style P5_Parallel fill:#ffe1f5
184    style P4 fill:#fff3cd
185    style Complete fill:#28a745,color:#fff
186```
187 
188### Parallel Execution Rules
189 
190<execution_rules>
191    <phase name="1-discovery" type="parallel" critical="true" spawn="single_message">
192        <gate>
193        **STOP.** Verify parallel spawn requirements.
194        **REQUIRED:** Spawn 4 agents in ONE message.
195        **FORBIDDEN:** Sequential Task calls.
196        </gate>
197        <agent_count>4</agent_count>
198        <description>Discovery and Analysis</description>
199        <spawn_instruction>⚠️ Launch ALL 4 Task calls in ONE response</spawn_instruction>
200        <rules>
201            <rule>All 4 agents start simultaneously via single-message spawn</rule>
202            <rule>Wait for ALL 4 to complete before aggregation</rule>
203            <rule>Must aggregate 4 partial JSONs into analysis.json</rule>
204        </rules>
205    </phase>
206 
207    <phase name="2-questions" type="single" critical="true" spawn="sequential">
208        <agent_count>1</agent_count>
209        <description>Engineer Questions Generation</description>
210        <spawn_instruction>Single agent, wait for completion</spawn_instruction>
211    </phase>
212 
213    <phase name="3-research" type="parallel" critical="true" spawn="single_message">
214        <gate>
215        **STOP.** Verify parallel spawn requirements.
216        **REQUIRED:** Spawn N researchers in ONE message.
217        **FORBIDDEN:** Sequential Task calls.
218        </gate>
219        <agent_count_logic>
220            <case condition="questions &lt; 10">1 agent</case>
221            <case condition="questions &gt;= 10">Ceil(questions / 15)</case>
222        </agent_count_logic>
223        <description>Evidence Gathering</description>
224        <spawn_instruction>⚠️ Launch ALL researcher Task calls in ONE response</spawn_instruction>
225        <rules>
226            <rule>Split questions into batches BEFORE spawning</rule>
227            <rule>All researchers start simultaneously</rule>
228            <rule>Aggregate findings into research.json</rule>
229        </rules>
230    </phase>
231 
232    <phase name="4-orchestrator" type="single" critical="true" spawn="sequential">
233        <agent_count>1</agent_count>
234        <description>Orchestration and Assignment</description>
235        <spawn_instruction>Single agent, wait for completion</spawn_instruction>
236        <rules>
237            <rule>Assign EXCLUSIVE file ownership to writers</rule>
238            <rule>Distribute research findings to relevant writers</rule>
239        </rules>
240    </phase>
241 
242    <phase name="5-writers" type="dynamic_parallel" critical="false" spawn="single_message">
243        <gate>
244        **STOP.** Verify parallel spawn requirements.
245        **REQUIRED:** Spawn all writers in ONE message.
246        **FORBIDDEN:** Sequential Task calls.
247        </gate>
248        <agent_count_logic>
249            <case condition="questions &lt; 20">1 agent</case>
250            <case condition="questions 20-99">2-4 agents</case>
251            <case condition="questions &gt;= 100">4-8 agents</case>
252        </agent_count_logic>
253        <spawn_instruction>⚠️ Launch ALL writer Task calls in ONE response</spawn_instruction>
254        <rules>
255            <rule>Each writer owns EXCLUSIVE files - no conflicts possible</rule>
256            <rule>All writers start simultaneously via single-message spawn</rule>
257            <rule>Use provided research.json as primary source</rule>
258        </rules>
259    </phase>
260 
261    <phase name="6-qa" type="single" critical="false" spawn="sequential">
262        <agent_count>1</agent_count>
263        <description>Quality Validation</description>
264        <spawn_instruction>Single agent, wait for completion</spawn_instruction>
265    </phase>
266</execution_rules>
267 
268## Pre-Flight Checks
269 
270<pre_flight_gate>
271**HALT. Complete these requirements before proceeding:**
272 
273### Required Checks
2741. **Verify Path Existence**
275   - **IF** `repository_path` missing → **THEN** ERROR & EXIT
2762. **Verify Directory Status**
277   - **IF** not a directory → **THEN** ERROR & EXIT
2783. **Source Code Check**
279   - **IF** < 3 source files → **THEN** WARN & Ask User (Exit if no)
2804. **Build Directory Check**
281   - **IF** contains `node_modules` or `dist` → **THEN** ERROR & EXIT
2825. **Size Estimation**
283   - **IF** > 200k LOC → **THEN** WARN & Ask User (Exit if no)
284 
285**FORBIDDEN until gate passes:**
286- Any agent spawning
287- Workspace initialization
288</pre_flight_gate>
289 
290<instruction>
291Before starting, validate the repository path and check for edge cases.
292 
2931. **Verify Path Existence**
294   - Ensure `repository_path` exists.
295   - If not, raise an ERROR: "Repository path does not exist: " + path and EXIT.
296 
2972. **Verify Directory Status**
298   - Confirm `repository_path` is a directory.
299   - If not, raise an ERROR: "Path is not a directory: " + path and EXIT.
300 
3013. **Source Code Check**
302   - Count files ending in `.ts`, `.js`, `.py`, `.go`, or `.rs`.
303   - Exclude directories: `node_modules`, `.git`, `dist`, `build`.
304   - If fewer than 3 source files are found:
305     - WARN: "Very few source files detected ({count}). This may not be a code repository."
306     - Ask user: "Continue anyway? [y/N]"
307     - If not confirmed, EXIT.
308 
3094. **Build Directory Check**
310   - Ensure the path does not contain `node_modules`, `dist`, or `build`.
311   - If it does, raise an ERROR: "Repository path appears to be a build directory. Please specify the project root." and EXIT.
312 
3135. **Size Estimation**
314   - Estimate the repository size.
315   - If larger than 200,000 LOC:
316     - WARN: "Large repository detected (~{size} LOC)."
317     - Ask user: "Continue anyway? [y/N]"
318     - If not confirmed, EXIT.
319</instruction>
320 
321## Initialize Workspace
322 
323<init_gate>
324**STOP. Verify state before initialization.**
325 
326### Required Actions
3271. **Define Directories** (`CONTEXT_DIR`, `DOC_DIR`)
3282. **Handle Existing State**
329   - **IF** `state.json` exists → **THEN** Prompt User to Resume
330   - **IF** User says NO → **THEN** Reset state
3313. **Create Directories**
3324. **Initialize New State** (if not resuming)
333 
334**FORBIDDEN:**
335- Starting Phase 1 before state is initialized.
336</init_gate>
337 
338<instruction>
339### Workspace Initialization
340Before starting the pipeline, set up the working environment and handle any existing state.
341 
3421. **Define Directories**
343   - Context Directory (`CONTEXT_DIR`): `${REPOSITORY_PATH}/.context`
344   - Documentation Directory (`DOC_DIR`): `${REPOSITORY_PATH}/documentation`
345 
3462. **Handle Existing State**
347   - Check if `${CONTEXT_DIR}/state.json` exists.
348   - If it exists and the phase is NOT "complete" or "failed":
349     - **Prompt User**: "Found existing documentation generation in progress (phase: [PHASE]). Resume from last checkpoint? [Y/n]"
350     - **If User Confirms (Yes)**:
351       - Set `RESUME_MODE = true`
352       - Set `START_PHASE` from the saved state.
353     - **If User Declines (No)**:
354       - **WARN**: "Restarting from beginning. Previous progress will be overwritten."
355       - Set `RESUME_MODE = false`
356       - Set `START_PHASE = "initialized"`
357   - If `state.json` does not exist or previous run finished/failed, start fresh (`RESUME_MODE = false`).
358 
3593. **Create Directories**
360   - Ensure `CONTEXT_DIR` exists (create if missing).
361   - Ensure `DOC_DIR` exists (create if missing).
362 
3634. **Initialize New State** (If NOT Resuming)
364   - Create a new `state.json` using the schema defined in `schemas/state-schema.json`.
365</instruction>
366 
367## Progress Tracker
368 
369Display real-time progress:
370 
371```
372📊 Documentation Generation Progress v3.1
373━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
374 
375Repository: {REPOSITORY_PATH}
376Mode: {RESUME_MODE ? "Resume" : "New"}
377 
378{if RESUME_MODE}
379Resuming from: {START_PHASE}
380{end}
381 
382━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
383```
384 
385## Agent Pipeline Execution
386 
387### Phase 1: Discovery+Analysis Agent
388 
389<phase_1_gate>
390**GATE: START Phase 1**
391**REQUIRED:** Spawn 4 agents in **ONE** message.
392**FORBIDDEN:** Sequential calls.
393</phase_1_gate>
394 
395**Agent Spec**: `references/agent-discovery-analysis.md`
396**Task Config**: `schemas/discovery-tasks.json`
397 
398| Property | Value |
399|----------|-------|
400| Parallel Agents | 4 (1a-language, 1b-components, 1c-dependencies, 1d-flows-apis) |
401| Critical | Yes |
402| Output | `.context/analysis.json` |
403 
404> See `references/agent-discovery-analysis.md` → **Orchestrator Execution Logic** section for full implementation.
405 
406### Phase 2: Engineer Questions Agent
407 
408**Agent Spec**: `references/agent-engineer-questions.md`
409 
410| Property | Value |
411|----------|-------|
412| Agent Type | Single (Opus) |
413| Critical | Yes |
414| Input | `.context/analysis.json` |
415| Output | `.context/questions.json` |
416 
417> See `references/agent-engineer-questions.md` → **Orchestrator Execution Logic** section for full implementation.
418 
419 
420### Phase 3: Research Agent 🆕
421 
422<phase_3_gate>
423**GATE: START Phase 3**
424**REQUIRED:** Spawn N agents in **ONE** message.
425**FORBIDDEN:** Sequential calls.
426</phase_3_gate>
427 
428**Agent Spec**: `references/agent-researcher.md`
429 
430| Property | Value |
431|----------|-------|
432| Agent Type | Parallel (Sonnet) |
433| Critical | Yes |
434| Input | `.context/questions.json` |
435| Output | `.context/research.json` |
436 
437> See `references/agent-researcher.md` → **Orchestrator Execution Logic** section for full implementation.
438 
439 
440### Phase 4: Orchestrator Agent
441 
442**Agent Spec**: `references/agent-orchestrator.md`
443 
444| Property | Value |
445|----------|-------|
446| Agent Type | Single (Opus) |
447| Critical | Yes |
448| Input | `.context/analysis.json`, `.context/questions.json`, `.context/research.json` |
449| Output | `.context/work-assignments.json` |
450 
451> See `references/agent-orchestrator.md` → **Orchestrator Execution Logic** section for full implementation.
452 
453### Phase 5: Documentation Writers
454 
455<phase_5_gate>
456**GATE: START Phase 5**
457**REQUIRED:** Spawn all writers in **ONE** message.
458**FORBIDDEN:** Sequential calls.
459</phase_5_gate>
460 
461**Agent Spec**: `references/agent-documentation-writer.md`
462 
463| Property | Value |
464|----------|-------|
465| Agent Type | Parallel (1-8 Sonnet writers) |
466| Primary Writer | Writer 1 (Critical) |
467| Non-Primary | Partial failure allowed |
468| Retry Logic | Up to 2 retries per failed writer |
469| Input | `.context/analysis.json`, `.context/research.json`, `.context/work-assignments.json` |
470| Output | `documentation/*.md` (16 core, 5 required + supplementary) |
471| File Ownership | Exclusive (no conflicts) |
472 
473#### Writer Scaling Strategy
474 
475| Strategy | Agent Count | When Used |
476|----------|-------------|-----------|
477| `sequential` | 1 | < 20 questions |
478| `parallel-core` | 2-4 | 20-99 questions |
479| `parallel-all` | 4-8 | >= 100 questions |
480 
481> See `references/agent-documentation-writer.md` → **Orchestrator Execution Logic** section for full implementation.
482 
483### Phase 6: QA Validator
484 
485**Agent Spec**: `references/agent-qa-validator.md`
486 
487| Property | Value |
488|----------|-------|
489| Agent Type | Single (Sonnet) |
490| Critical | No (failure produces warning) |
491| Input | `.context/analysis.json`, `.context/questions.json`, `documentation/*.md` |
492| Output | `.context/qa-results.json`, `documentation/QA-SUMMARY.md` |
493| Score Range | 0-100 |
494| Quality Ratings | `excellent` (≥90), `good` (≥75), `fair` (≥60), `needs-improvement` (<60) |
495 
496> See `references/agent-qa-validator.md` → **Orchestrator Execution Logic** section for full implementation.
497 
498## Completion
499 
500```javascript
501update_state({
502  phase: "complete",
503  completed_at: new Date().toISOString(),
504  current_agent: null
505})
506 
507DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
508DISPLAY: "✅ Documentation Complete!"
509DISPLAY: ""
510DISPLAY: "📁 Location: {DOC_DIR}/"
511DISPLAY: "📊 QA Report: {DOC_DIR}/QA-SUMMARY.md"
512DISPLAY: ""
513 
514if (parsed_qa && parsed_qa.overall_score):
515  DISPLAY: "Quality Score: {parsed_qa.overall_score}/100 ({parsed_qa.quality_rating})"
516 
517  if (parsed_qa.overall_score >= 90):
518    DISPLAY: "Status: Excellent ✅ - Ready for release"
519  else if (parsed_qa.overall_score >= 75):
520    DISPLAY: "Status: Good ✅ - Minor improvements recommended"
521  else if (parsed_qa.overall_score >= 60):
522    DISPLAY: "Status: Fair -️ - Address gaps before release"
523  else:
524    DISPLAY: "Status: Needs Work -️ - Major improvements required"
525 
526  if (parsed_qa.gaps && parsed_qa.gaps.length > 0):
527    DISPLAY: ""
528    DISPLAY: "Next Steps:"
529    for (i = 0; i < Math.min(3, parsed_qa.gaps.length); i++):
530      gap = parsed_qa.gaps[i]
531      DISPLAY: "  {i+1}. {gap.fix}"
532 
533DISPLAY: ""
534DISPLAY: "📝 Documentation Coverage:"
535DISPLAY: "   {parsed_questions.summary.total_questions} questions researched"
536DISPLAY: "   {parsed_qa.question_coverage.answered} questions answered in docs"
537DISPLAY: ""
538DISPLAY: "View documentation: {DOC_DIR}/index.md"
539DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
540 
541EXIT code 0
542```
543 
544## Error Recovery
545 
546If any agent fails critically:
547 
548```javascript
549function handle_critical_failure(phase, error):
550  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
551  DISPLAY: "❌ Documentation Generation Failed"
552  DISPLAY: ""
553  DISPLAY: "Phase: {phase}"
554  DISPLAY: "Error: {error.message}"
555  DISPLAY: ""
556 
557  if (error.recoverable):
558    DISPLAY: "This error is recoverable. Run /octocode-documentation-writer again to resume."
559    DISPLAY: "State saved in: {CONTEXT_DIR}/state.json"
560  else:
561    DISPLAY: "This error is not recoverable. Please check the error and try again."
562    DISPLAY: "You may need to fix the issue before retrying."
563 
564  DISPLAY: ""
565  DISPLAY: "Logs: {CONTEXT_DIR}/state.json"
566  DISPLAY: "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
567 
568  EXIT code 1
569```
570 
571## Helper Functions
572 
573> **IMPORTANT: State Synchronization**
574> Only the main orchestrator process should update `state.json`. Individual parallel agents
575> (Discovery 1A-1D, Researchers, Writers) must NOT directly modify `state.json` to avoid
576> race conditions. Parallel agents should only write to their designated partial result files
577> in `partials/<phase>/<task_id>.json`. The orchestrator aggregates these results and updates
578> `state.json` after all parallel agents complete.
579 
580```javascript
581// NOTE: This function should ONLY be called by the main orchestrator process,
582// never by parallel sub-agents. Parallel agents use save_partial_result() instead.
583function update_state(updates):
584  current_state = Read(CONTEXT_DIR + "/state.json")
585  parsed = JSON.parse(current_state)
586 
587  for key, value in updates:
588    parsed[key] = value
589 
590  Write(CONTEXT_DIR + "/state.json", JSON.stringify(parsed, null, 2))
591 
592function estimate_repo_size(path):
593  // Quick estimate: count source files
594  files = count_files(path, ["*.ts", "*.js", "*.py", "*.go", "*.rs", "*.java"], excludeDir=["node_modules", ".git", "dist", "build"])
595  // Assume ~200 LOC per file average
596  return files * 200
597 
598function count_files(path, patterns, excludeDir):
599  // Use localFindFiles MCP tool (mcp__octocode__localFindFiles)
600  // Return count of matching files
601```
602 
603## Retry & Data Preservation Logic
604 
605**CRITICAL**: Never lose partial work. All agents support retry with state preservation.
606 
607```javascript
608const RETRY_CONFIG = {
609  discovery_analysis: { max_attempts: 3, backoff_ms: 2000 },
610  engineer_questions: { max_attempts: 3, backoff_ms: 2000 },
611  research:           { max_attempts: 3, backoff_ms: 3000 },
612  orchestrator:       { max_attempts: 3, backoff_ms: 2000 },
613  documentation:      { max_attempts: 3, backoff_ms: 5000 },  // per writer
614  qa:                 { max_attempts: 2, backoff_ms: 1000 }
615}
616 
617// === RETRY WRAPPER FOR ALL AGENTS ===
618function retry_agent(phase_name, agent_fn, options = {}):
619  config = RETRY_CONFIG[phase_name]
620  state = get_retry_state(phase_name)
621 
622  while (state.attempts < config.max_attempts):
623    state.attempts++
624    update_retry_state(phase_name, state)
625 
626    DISPLAY: `⟳ ${phase_name} attempt ${state.attempts}/${config.max_attempts}`
627 
628    try:
629      result = agent_fn(options)
630 
631      // Success - clear retry state
632      clear_retry_state(phase_name)
633      return { success: true, result }
634 
635    catch (error):
636      state.last_error = error.message
637      update_retry_state(phase_name, state)
638 
639      DISPLAY: `⚠️ ${phase_name} failed: ${error.message}`
640 
641      if (state.attempts < config.max_attempts):
642        DISPLAY: `   Retrying in ${config.backoff_ms}ms...`
643        sleep(config.backoff_ms * state.attempts)  // Exponential backoff
644      else:
645        DISPLAY: `❌ ${phase_name} exhausted all ${config.max_attempts} attempts`
646        return { success: false, error, attempts: state.attempts }
647 
648  return { success: false, error: state.last_error, attempts: state.attempts }
649 
650// === PARALLEL AGENT RETRY (for Discovery, Research, Writers) ===
651function retry_parallel_agents(phase_name, agent_tasks, options = {}):
652  config = RETRY_CONFIG[phase_name]
653  results = {}
654  failed_tasks = []
655 
656  // First attempt - run all in parallel
657  parallel_results = Task_Parallel(agent_tasks)
658 
659  for (task_id, result) in parallel_results:
660    if (result.success):
661      results[task_id] = result
662      save_partial_result(phase_name, task_id, result)
663    else:
664      failed_tasks.push({ id: task_id, task: agent_tasks[task_id], attempts: 1 })
665 
666  // Retry failed tasks individually
667  for failed in failed_tasks:
668    while (failed.attempts < config.max_attempts):
669      failed.attempts++
670      DISPLAY: `⟳ Retrying ${phase_name}/${failed.id} (attempt ${failed.attempts}/${config.max_attempts})`
671 
672      try:
673        result = Task(failed.task)
674        if (result.success):
675          results[failed.id] = result
676          save_partial_result(phase_name, failed.id, result)
677          break
678      catch (error):
679        DISPLAY: `⚠️ ${phase_name}/${failed.id} failed: ${error.message}`
680        if (failed.attempts < config.max_attempts):
681          sleep(config.backoff_ms * failed.attempts)
682 
683    if (failed.attempts >= config.max_attempts && !results[failed.id]):
684      DISPLAY: `❌ ${phase_name}/${failed.id} failed after ${config.max_attempts} attempts`
685      // Load any partial result saved during attempts
686      results[failed.id] = load_partial_result(phase_name, failed.id) || { success: false, partial: true }
687 
688  return results
689 
690// === PARTIAL RESULT PRESERVATION ===
691// Uses atomic writes to prevent corruption from concurrent access
692function save_partial_result(phase_name, task_id, result):
693  partial_dir = CONTEXT_DIR + "/partials/" + phase_name
694  mkdir_p(partial_dir)
695 
696  target_path = partial_dir + "/" + task_id + ".json"
697  temp_path = partial_dir + "/" + task_id + ".json.tmp." + random_uuid()
698 
699  // Atomic write: write to temp file, then rename (rename is atomic on POSIX)
700  Write(temp_path, JSON.stringify(result))
701  rename(temp_path, target_path)  // Atomic operation
702 
703function load_partial_result(phase_name, task_id):
704  path = CONTEXT_DIR + "/partials/" + phase_name + "/" + task_id + ".json"
705  if (exists(path)):
706    return JSON.parse(Read(path))
707  return null
708 
709function load_all_partial_results(phase_name):
710  partial_dir = CONTEXT_DIR + "/partials/" + phase_name
711  if (!exists(partial_dir)):
712    return {}
713  files = list_files(partial_dir, "*.json")
714  results = {}
715  for file in files:
716    task_id = file.replace(".json", "")
717    results[task_id] = JSON.parse(Read(partial_dir + "/" + file))
718  return results
719 
720// === RETRY STATE MANAGEMENT ===
721function get_retry_state(phase_name):
722  state = Read(CONTEXT_DIR + "/state.json")
723  parsed = JSON.parse(state)
724  return parsed.retry_state?.[phase_name] || { attempts: 0 }
725 
726function update_retry_state(phase_name, retry_state):
727  update_state({
728    retry_state: {
729      ...current_state.retry_state,
730      [phase_name]: retry_state
731    }
732  })
733 
734function clear_retry_state(phase_name):
735  state = JSON.parse(Read(CONTEXT_DIR + "/state.json"))
736  if (state.retry_state):
737    delete state.retry_state[phase_name]
738    Write(CONTEXT_DIR + "/state.json", JSON.stringify(state, null, 2))
739```
740 
741### Phase-Specific Retry Behavior
742 
743| Phase | Retry Strategy | Partial Data Preserved |
744|-------|----------------|------------------------|
745| **Discovery** | Retry failed sub-agents (1A-1D) individually | `partials/discovery/*.json` |
746| **Questions** | Retry entire phase | Previous `questions.json` kept until success |
747| **Research** | Retry failed batches only | `partials/research/batch-*.json` |
748| **Orchestrator** | Retry entire phase | Previous `work-assignments.json` kept |
749| **Writers** | Retry failed writers only | `partials/writers/writer-*.json` + completed files |
750| **QA** | Retry once, then warn | `partials/qa/partial-results.json` |
751 
752### Critical Data Protection Rules
753 
754```javascript
755// RULE 1: Never overwrite successful output until new output is validated
756function safe_write_output(path, content):
757  backup_path = path + ".backup"
758  if (exists(path)):
759    copy(path, backup_path)
760 
761  try:
762    Write(path, content)
763    validate_json(path)  // Ensure valid JSON
764    delete(backup_path)  // Only delete backup after validation
765  catch (error):
766    // Restore from backup
767    if (exists(backup_path)):
768      copy(backup_path, path)
769    throw error
770 
771// RULE 2: Aggregate partial results even on failure
772// Uses file locking to prevent race conditions during aggregation
773function aggregate_with_partials(phase_name, new_results):
774  lock_file = CONTEXT_DIR + "/partials/" + phase_name + "/.aggregate.lock"
775 
776  // Acquire exclusive lock before aggregation
777  lock_fd = acquire_file_lock(lock_file, timeout_ms=5000)
778  if (!lock_fd):
779    throw new Error("Failed to acquire lock for aggregation: " + phase_name)
780 
781  try:
782    existing = load_all_partial_results(phase_name)
783    merged = { ...existing, ...new_results }
784    return merged
785  finally:
786    release_file_lock(lock_fd)
787    delete(lock_file)
788 
789// RULE 3: Resume-aware execution
790function should_skip_task(phase_name, task_id):
791  partial = load_partial_result(phase_name, task_id)
792  return partial?.success === true
793```
794---
795 
796## Key Features
797 
798<key_features>
799 
800| # | Feature | Description |
801|---|---------|-------------|
802| 1 | **True Parallel Execution** | Phases 1, 3, 5 spawn ALL agents in ONE message for concurrent execution |
803| 2 | **Single-Message Spawn** | ⚠️ Critical: Multiple Task calls in one response = true parallelism |
804| 3 | **Evidence-Based** | Research agent proves answers with code traces before writing |
805| 4 | **Engineer-Driven Questions** | Phase 2 generates comprehensive questions |
806| 5 | **Conflict-Free Writing** | Orchestrator assigns exclusive file ownership per writer |
807| 6 | **LSP-Powered** | Intelligent verification with semantic analysis |
808| 7 | **State Recovery** | Resume from any phase if interrupted |
809| 8 | **Unified Toolset** | All agents use octocode local + LSP tools |
810| 9 | **Dynamic Scaling** | Agent count scales based on question volume |
811 
812</key_features>
813 
814<efficiency_summary>
815### Efficiency Maximization
816 
817```
818Phase 1: 4 agents × parallel = ~4x faster than sequential
819Phase 3: N agents × parallel = ~Nx faster than sequential
820Phase 5: M agents × parallel = ~Mx faster than sequential
821 
822Total speedup: Significant when spawn="single_message" is followed
823```
824 
825**Remember**: `spawn="single_message"` phases MUST have all Task calls in ONE response.
826</efficiency_summary>
827 
828---
829