maestro-flow 0.5.31 → 0.5.33

package/.agents/skills/team-frontend-debug/roles/coordinator/commands/dispatch.md

@@ -0,0 +1,256 @@
+# Dispatch Debug Tasks
+
+Create task chains from dependency graph with proper blockedBy relationships.
+
+## Workflow
+
+1. Read task-analysis.json -> extract pipeline_type and dependency_graph
+2. Read specs/pipelines.md -> get task registry for selected pipeline
+3. Topological sort tasks (respect blockedBy)
+4. Validate all owners exist in role registry (SKILL.md)
+5. For each task (in order):
+   - create_task with structured description (see template below)
+   - update_task with blockedBy + owner assignment
+6. Update team-session.json with pipeline.tasks_total
+7. Validate chain (no orphans, no cycles, all refs valid)
+
+## Task Description Template
+
+```
+PURPOSE: <goal> | Success: <criteria>
+TASK:
+  - <step 1>
+  - <step 2>
+CONTEXT:
+  - Session: <session-folder>
+  - Base URL / Bug URL: <url>
+  - Upstream artifacts: <list>
+EXPECTED: <artifact path> + <quality criteria>
+CONSTRAINTS: <scope limits>
+---
+InnerLoop: <true|false>
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/<role>/role.md
+```
+
+---
+
+## Test Pipeline Tasks (mode: test-pipeline)
+
+### TEST-001: Feature Testing
+
+```
+PURPOSE: Test all features from feature list and discover issues | Success: All features tested with pass/fail results
+TASK:
+  - Parse feature list from task description
+  - For each feature: navigate to URL, explore page, generate test scenarios
+  - Execute test scenarios using Chrome DevTools MCP (click, fill, hover, etc.)
+  - Capture evidence: screenshots, console logs, network requests
+  - Classify results: pass / fail / warning
+  - Compile test report with discovered issues
+CONTEXT:
+  - Session: <session-folder>
+  - Base URL: <base-url>
+  - Features: <feature-list-from-task-analysis>
+EXPECTED: <session>/artifacts/TEST-001-report.md + <session>/artifacts/TEST-001-issues.json
+CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code | Test all listed features
+---
+InnerLoop: true
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/tester/role.md
+```
+
+### ANALYZE-001 (Test Mode): Analyze Discovered Issues
+
+```
+PURPOSE: Analyze issues discovered by tester to identify root causes | Success: RCA for each discovered issue
+TASK:
+  - Load test report and issues list from TEST-001
+  - For each high/medium severity issue: analyze evidence, identify root cause
+  - Correlate console errors, network failures, DOM anomalies to source code
+  - Produce consolidated RCA report covering all issues
+CONTEXT:
+  - Session: <session-folder>
+  - Upstream: <session>/artifacts/TEST-001-issues.json
+  - Test evidence: <session>/evidence/
+EXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root causes for all issues
+CONSTRAINTS: Read-only analysis | Skip low-severity warnings unless user requests
+---
+InnerLoop: false
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/analyzer/role.md
+```
+
+**Conditional**: If TEST-001 reports zero issues → skip ANALYZE-001, FIX-001, VERIFY-001. Pipeline completes.
+
+### FIX-001 (Test Mode): Fix All Issues
+
+```
+PURPOSE: Fix all identified issues from RCA | Success: All high/medium issues resolved
+TASK:
+  - Load consolidated RCA report from ANALYZE-001
+  - For each root cause: locate code, implement fix
+  - Run syntax/type check after all modifications
+  - Document all changes
+CONTEXT:
+  - Session: <session-folder>
+  - Upstream: <session>/artifacts/ANALYZE-001-rca.md
+EXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md
+CONSTRAINTS: Minimal changes per issue | Follow existing code style
+---
+InnerLoop: true
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
+```
+
+### VERIFY-001 (Test Mode): Re-Test After Fix
+
+```
+PURPOSE: Re-run failed test scenarios to verify fixes | Success: Previously failed scenarios now pass
+TASK:
+  - Load original test report (failed scenarios only)
+  - Re-execute failed scenarios using Chrome DevTools MCP
+  - Capture evidence and compare with original
+  - Report pass/fail per scenario
+CONTEXT:
+  - Session: <session-folder>
+  - Original test report: <session>/artifacts/TEST-001-report.md
+  - Fix changes: <session>/artifacts/FIX-001-changes.md
+  - Failed features: <from TEST-001-issues.json>
+EXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail per previously-failed scenario
+CONSTRAINTS: Only re-test failed scenarios | Use Chrome DevTools MCP only
+---
+InnerLoop: false
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/verifier/role.md
+```
+
+---
+
+## Debug Pipeline Tasks (mode: debug-pipeline)
+
+### REPRODUCE-001: Evidence Collection
+
+```
+PURPOSE: Reproduce reported bug and collect debug evidence | Success: Bug reproduced with evidence artifacts
+TASK:
+  - Navigate to target URL
+  - Execute reproduction steps using Chrome DevTools MCP
+  - Capture evidence: screenshots, DOM snapshots, console logs, network requests
+  - If performance dimension: run performance trace
+  - Package all evidence into session evidence/ directory
+CONTEXT:
+  - Session: <session-folder>
+  - Bug URL: <target-url>
+  - Steps: <reproduction-steps>
+  - Evidence plan: <from task-analysis.json>
+EXPECTED: <session>/evidence/ directory with all captures + reproduction report
+CONSTRAINTS: Use Chrome DevTools MCP only | Do not modify any code
+---
+InnerLoop: false
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/reproducer/role.md
+```
+
+### ANALYZE-001 (Debug Mode): Root Cause Analysis
+
+```
+PURPOSE: Analyze evidence to identify root cause | Success: RCA report with specific file:line location
+TASK:
+  - Load evidence from REPRODUCE-001
+  - Analyze console errors and stack traces
+  - Analyze failed/abnormal network requests
+  - Compare DOM snapshot against expected structure
+  - Correlate findings to source code location
+CONTEXT:
+  - Session: <session-folder>
+  - Upstream: <session>/evidence/
+  - Bug description: <bug-description>
+EXPECTED: <session>/artifacts/ANALYZE-001-rca.md with root cause, file:line, fix recommendation
+CONSTRAINTS: Read-only analysis | Request more evidence if inconclusive
+---
+InnerLoop: false
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/analyzer/role.md
+```
+
+### FIX-001 (Debug Mode): Code Fix
+
+```
+PURPOSE: Fix the identified bug | Success: Code changes that resolve the root cause
+TASK:
+  - Load RCA report from ANALYZE-001
+  - Locate the problematic code
+  - Implement fix following existing code patterns
+  - Run syntax/type check on modified files
+CONTEXT:
+  - Session: <session-folder>
+  - Upstream: <session>/artifacts/ANALYZE-001-rca.md
+EXPECTED: Modified source files + <session>/artifacts/FIX-001-changes.md
+CONSTRAINTS: Minimal changes | Follow existing code style | No breaking changes
+---
+InnerLoop: true
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
+```
+
+### VERIFY-001 (Debug Mode): Fix Verification
+
+```
+PURPOSE: Verify bug is fixed | Success: Original bug no longer reproduces
+TASK:
+  - Navigate to same URL as REPRODUCE-001
+  - Execute same reproduction steps
+  - Capture evidence and compare with original
+  - Confirm bug is resolved and no regressions
+CONTEXT:
+  - Session: <session-folder>
+  - Original evidence: <session>/evidence/
+  - Fix changes: <session>/artifacts/FIX-001-changes.md
+EXPECTED: <session>/artifacts/VERIFY-001-report.md with pass/fail verdict
+CONSTRAINTS: Use Chrome DevTools MCP only | Same steps as reproduction
+---
+InnerLoop: false
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/verifier/role.md
+```
+
+---
+
+## Dynamic Iteration Tasks
+
+### REPRODUCE-002 (Debug Mode): Supplemental Evidence
+
+Created when Analyzer requests more evidence:
+```
+PURPOSE: Collect additional evidence per Analyzer request | Success: Targeted evidence collected
+TASK: <specific evidence requests from Analyzer>
+CONTEXT: Session + Analyzer request
+---
+InnerLoop: false
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/reproducer/role.md
+```
+
+### FIX-002 (Either Mode): Re-Fix After Failed Verification
+
+Created when Verifier reports fail:
+```
+PURPOSE: Re-fix based on verification failure feedback | Success: Issue resolved
+TASK: Review VERIFY-001 failure details, apply corrective fix
+CONTEXT: Session + VERIFY-001-report.md
+---
+InnerLoop: true
+RoleSpec: ~  or <project>/.claude/skills/team-frontend-debug/roles/fixer/role.md
+```
+
+## Conditional Skip Rules
+
+| Condition | Action |
+|-----------|--------|
+| test-pipeline + TEST-001 finds 0 issues | Skip ANALYZE/FIX/VERIFY → pipeline complete |
+| test-pipeline + TEST-001 finds only warnings | ask_user: fix warnings or complete |
+| debug-pipeline + REPRODUCE-001 cannot reproduce | ask_user: retry with more info or abort |
+
+## InnerLoop Flag Rules
+
+- true: tester (iterates over features), fixer (may need multiple fix passes)
+- false: reproducer, analyzer, verifier (single-pass tasks)
+
+## Dependency Validation
+
+- No orphan tasks (all tasks have valid owner)
+- No circular dependencies
+- All blockedBy references exist
+- Session reference in every task description
+- RoleSpec reference in every task description

package/.agents/skills/team-frontend-debug/roles/coordinator/commands/monitor.md

@@ -0,0 +1,148 @@
+# monitor_process Pipeline
+
+Event-driven pipeline coordination. Beat model: coordinator wake -> process -> spawn -> STOP.
+
+## Constants
+
+- SPAWN_MODE: background
+- ONE_STEP_PER_INVOCATION: true
+- FAST_ADVANCE_AWARE: true
+- WORKER_AGENT: team-worker
+
+## Handler Router
+
+| Source | Handler |
+|--------|---------|
+| Message contains [role-name] | handleCallback |
+| "need_more_evidence" | handleIteration |
+| "check" or "status" | handleCheck |
+| "resume" or "continue" | handleResume |
+| All tasks completed | handleComplete |
+| Default | handleSpawnNext |
+
+## handleCallback
+
+Worker completed. Process and advance.
+
+1. Find matching worker by role in message
+2. Check if progress update (inner loop) or final completion
+3. Progress -> update session state, STOP
+4. Completion -> mark task done, remove from active_workers
+5. Check for special conditions:
+   - **TEST-001 with 0 issues** -> skip ANALYZE/FIX/VERIFY (mark as completed), handleComplete
+   - **TEST-001 with only warnings** -> ask_user: fix warnings or complete
+   - **TEST-001 with high/medium issues** -> proceed to ANALYZE-001
+   - ANALYZE-001 with `need_more_evidence: true` -> handleIteration
+   - VERIFY-001 with `verdict: fail` -> re-dispatch FIX (create FIX-002 blocked by VERIFY-001)
+   - VERIFY-001 with `verdict: pass` -> handleComplete
+6. -> handleSpawnNext
+
+## handleIteration
+
+Analyzer needs more evidence. Create supplemental reproduction task.
+
+1. Parse Analyzer's evidence request (dimensions, specific actions)
+2. Create REPRODUCE-002 task:
+   - create_task with description from Analyzer's request
+   - update_task to set owner (no blockedBy — can start immediately)
+3. Create ANALYZE-002 task:
+   - create_task + update_task with addBlockedBy: [REPRODUCE-002]
+   - update_task FIX-001 with addBlockedBy to include ANALYZE-002
+4. Update team-session.json with new tasks
+5. -> handleSpawnNext
+
+## handleCheck
+
+Read-only status report, then STOP.
+
+**Worker Progress** (from message bus):
+
+Before generating status output, read worker milestones:
+
+```javascript
+const progressMsgs = mcp__maestro__team_msg({
+  operation: "list", session_id: sessionId, type: "progress", last: 50
+})
+const blockerMsgs = mcp__maestro__team_msg({
+  operation: "list", session_id: sessionId, type: "blocker", last: 10
+})
+
+// Aggregate latest milestone per task
+const taskProgress = {}
+for (const msg of (progressMsgs.result?.messages || [])) {
+  const tid = msg.data?.task_id
+  if (tid && (!taskProgress[tid] || msg.ts > taskProgress[tid].ts)) {
+    taskProgress[tid] = { phase: msg.data.phase, pct: msg.data.progress_pct, ts: msg.ts }
+  }
+}
+```
+
+Include in status output:
+- Per-worker latest milestone (phase + progress_pct) next to task status
+- Active blockers section (if any blockerMsgs found)
+
+Output:
+```
+[coordinator] Debug Pipeline Status
+[coordinator] Bug: <bug-description-summary>
+[coordinator] Progress: <done>/<total> (<pct>%)
+[coordinator] Active: <workers with elapsed time>
+[coordinator] Ready: <pending tasks with resolved deps>
+[coordinator] Evidence: <list of collected evidence types>
+[coordinator] Commands: 'resume' to advance | 'check' to refresh
+```
+
+## handleResume
+
+1. No active workers -> handleSpawnNext
+2. Has active -> check each status
+   - completed -> mark done
+   - in_progress -> still running
+3. Some completed -> handleSpawnNext
+4. All running -> report status, STOP
+
+## handleSpawnNext
+
+Find ready tasks, spawn workers, STOP.
+
+1. Collect: completedSubjects, inProgressSubjects, readySubjects
+2. No ready + work in progress -> report waiting, STOP
+3. No ready + nothing in progress -> handleComplete
+4. Has ready -> for each:
+   a. Check if inner loop role with active worker -> skip (worker picks up)
+   b. Standard spawn:
+      - update_task -> in_progress
+      - team_msg log -> task_unblocked
+      - Spawn team-worker (see SKILL.md Worker Spawn Template)
+      - Add to active_workers
+5. Update session, output summary, STOP
+
+## handleComplete
+
+Pipeline done. Generate debug report and completion action.
+
+1. Generate debug summary:
+   - Bug description and reproduction results
+   - Root cause analysis (from ANALYZE artifacts)
+   - Code changes applied (from FIX artifacts)
+   - Verification verdict (from VERIFY artifacts)
+   - Evidence inventory (screenshots, logs, traces)
+2. Read session.completion_action:
+   - interactive -> ask_user (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean (status=completed, delete_team)
+   - auto_keep -> Keep Active (status=paused)
+
+## handleAdapt
+
+Not typically needed for debug pipeline. If Analyzer identifies a dimension not covered:
+
+1. Parse gap description
+2. Check if reproducer can cover it -> add to evidence plan
+3. Create supplemental REPRODUCE task
+
+## Fast-Advance Reconciliation
+
+On every coordinator wake:
+1. Read team_msg entries with type="fast_advance"
+2. Sync active_workers with spawned successors
+3. No duplicate spawns

package/.agents/skills/team-frontend-debug/roles/coordinator/role.md

@@ -0,0 +1,131 @@
+# Coordinator Role
+
+Orchestrate team-frontend-debug: analyze -> dispatch -> spawn -> monitor -> report.
+
+## Identity
+- Name: coordinator | Tag: [coordinator]
+- Responsibility: Analyze bug report -> Create team -> Dispatch debug tasks -> monitor_process progress -> Report results
+
+## Boundaries
+
+### MUST
+- Parse bug report description (text-level only, no codebase reading)
+- Create team and spawn team-worker agents in background
+- Dispatch tasks with proper dependency chains
+- monitor_process progress via callbacks and route messages
+- Maintain session state (team-session.json)
+- Handle iteration loops (analyzer requesting more evidence)
+- Execute completion action when pipeline finishes
+
+### MUST NOT
+- Read source code or explore codebase (delegate to workers)
+- Execute debug/fix work directly
+- Modify task output artifacts
+- Spawn workers with general-purpose agent (MUST use team-worker)
+- Generate more than 5 worker roles
+
+## Command Execution Protocol
+When coordinator needs to execute a specific phase:
+1. Read `commands/<command>.md`
+2. Follow the workflow defined in the command
+3. Commands are inline execution guides, NOT separate agents
+4. Execute synchronously, complete before proceeding
+
+## Entry Router
+
+| Detection | Condition | Handler |
+|-----------|-----------|---------|
+| Worker callback | Message contains [role-name] | -> handleCallback (monitor.md) |
+| Status check | Args contain "check" or "status" | -> handleCheck (monitor.md) |
+| Manual resume | Args contain "resume" or "continue" | -> handleResume (monitor.md) |
+| Iteration request | Message contains "need_more_evidence" | -> handleIteration (monitor.md) |
+| Pipeline complete | All tasks completed | -> handleComplete (monitor.md) |
+| Interrupted session | Active session in .workflow/.team/TFD-* | -> Phase 0 |
+| New session | None of above | -> Phase 1 |
+
+For callback/check/resume/iteration/complete: load commands/monitor.md, execute handler, STOP.
+
+## Phase 0: Session Resume Check
+
+1. Scan .workflow/.team/TFD-*/team-session.json for active/paused sessions
+2. No sessions -> Phase 1
+3. Single session -> reconcile:
+   a. Audit list_tasks, reset in_progress->pending
+   b. Rebuild team workers
+   c. Kick first ready task
+4. Multiple -> ask_user for selection
+
+## Phase 1: Requirement Clarification
+
+TEXT-LEVEL ONLY. No source code reading.
+
+1. Parse user input — detect mode:
+   - Feature list / 功能清单 → **test-pipeline**
+   - Bug report / 错误描述 → **debug-pipeline**
+   - Ambiguous → ask_user to clarify
+2. Extract relevant info based on mode:
+   - Test mode: base URL, feature list
+   - Debug mode: bug description, URL, reproduction steps
+3. Clarify if ambiguous (ask_user)
+4. Delegate to @commands/analyze.md
+5. Output: task-analysis.json
+6. CRITICAL: Always proceed to Phase 2, never skip team workflow
+
+## Phase 2: Create Team + Initialize Session
+
+1. Resolve workspace paths (MUST do first):
+   - `project_root` = result of `shell({ command: "pwd" })`
+   - `skill_root` = `<project_root>/.claude/skills/team-frontend-debug`
+2. Generate session ID: TFD-<slug>-<date>
+3. Create session folder structure:
+   ```
+   .workflow/.team/TFD-<slug>-<date>/
+   ├── team-session.json
+   ├── evidence/
+   ├── artifacts/
+   ├── wisdom/
+   └── .msg/
+   ```
+3. create_team with team name
+4. Read specs/pipelines.md -> select pipeline (default: debug-pipeline)
+5. Register roles in team-session.json
+6. Initialize pipeline via team_msg state_update
+7. Write team-session.json
+
+## Phase 3: Create Task Chain
+
+Delegate to @commands/dispatch.md:
+1. Read dependency graph from task-analysis.json
+2. Read specs/pipelines.md for debug-pipeline task registry
+3. Topological sort tasks
+4. Create tasks via create_task, then set blockedBy via update_task
+5. Update team-session.json
+
+## Phase 4: Spawn-and-Stop
+
+Delegate to @commands/monitor.md#handleSpawnNext:
+1. Find ready tasks (pending + blockedBy resolved)
+2. Spawn team-worker agents (see SKILL.md Spawn Template)
+3. Output status summary
+4. STOP
+
+## Phase 5: Report + Completion Action
+
+1. Generate debug summary:
+   - Bug description and reproduction results
+   - Root cause analysis findings
+   - Files modified and patches applied
+   - Verification results (pass/fail)
+2. Execute completion action per session.completion_action:
+   - interactive -> ask_user (Archive/Keep/Export)
+   - auto_archive -> Archive & Clean
+
+## Error Handling
+
+| Error | Resolution |
+|-------|------------|
+| Bug report too vague | ask_user for URL, steps, expected behavior |
+| Session corruption | Attempt recovery, fallback to manual |
+| Worker crash | Reset task to pending, respawn |
+| Dependency cycle | Detect in analysis, halt |
+| Browser unavailable | Report to user, suggest manual steps |

package/.agents/skills/team-frontend-debug/roles/fixer/role.md

@@ -0,0 +1,149 @@
+---
+role: fixer
+prefix: FIX
+inner_loop: true
+message_types:
+  success: fix_complete
+  progress: fix_progress
+  error: error
+---
+<!-- Open-standard mirror generated by scripts/build-agents-standard.mjs — do not edit; re-run after editing .claude/ source. -->
+
+
+# Fixer
+
+Code fix implementation based on root cause analysis.
+
+## Identity
+- Tag: [fixer] | Prefix: FIX-*
+- Responsibility: Implement code fixes based on RCA report, validate with syntax checks
+
+## Boundaries
+### MUST
+- Read RCA report before any code changes
+- Locate exact source code to modify
+- Follow existing code patterns and style
+- Run syntax/type check after modifications
+- Document all changes made
+### MUST NOT
+- Skip reading the RCA report
+- Make changes unrelated to the identified root cause
+- Introduce new dependencies without justification
+- Skip syntax validation after changes
+- Make breaking changes to public APIs
+
+## Phase 2: Parse RCA + Plan Fix
+
+1. Read upstream artifacts via team_msg(operation="get_state", role="analyzer")
+2. Extract RCA report path from analyzer's state_update ref
+3. Load RCA report: `<session>/artifacts/ANALYZE-001-rca.md`
+4. Extract:
+   - Root cause category and description
+   - Source file(s) and line(s)
+   - Recommended fix approach
+   - Risk level
+5. Read identified source files to understand context
+6. Search for similar patterns in codebase:
+   ```
+   ({
+     project_root_path: "<project-root>",
+     query: "<function/component name from RCA>"
+   })
+   ```
+7. Plan fix approach:
+   - Minimal change that addresses root cause
+   - Consistent with existing code patterns
+   - No side effects on other functionality
+
+## Phase 3: Implement Fix
+
+### Fix Strategy by Category
+
+| Category | Typical Fix | Tools |
+|----------|-------------|-------|
+| TypeError / null | Add null check, default value | Edit |
+| API Error | Fix URL, add error handling | Edit |
+| Missing import | Add import statement | Edit |
+| CSS/Rendering | Fix styles, layout properties | Edit |
+| State bug | Fix state update logic | Edit |
+| Race condition | Add proper async handling | Edit |
+| Performance | Optimize render, memoize | Edit |
+
+### Implementation Steps
+
+1. Read the target file(s)
+2. Apply minimal code changes using Edit tool
+3. If Edit fails, use mcp__maestro__edit_file as fallback
+4. For each modified file:
+   - Keep changes minimal and focused
+   - Preserve existing code style (indentation, naming)
+   - Add inline comment only if fix is non-obvious
+
+### Syntax Validation
+
+After all changes:
+```
+mcp__ide__getDiagnostics({ uri: "file://<modified-file>" })
+```
+
+If diagnostics show errors:
+- Fix syntax/type errors
+- Re-validate
+- Max 3 fix iterations for syntax issues
+
+## Phase 4: Document Changes + Report
+
+Write `<session>/artifacts/FIX-001-changes.md`:
+
+```markdown
+# Fix Report
+
+## Root Cause Reference
+- RCA: <session>/artifacts/ANALYZE-001-rca.md
+- Category: <category>
+- Source: <file:line>
+
+## Changes Applied
+
+### <file-path>
+- **Line(s)**: <line numbers>
+- **Change**: <description of what was changed>
+- **Reason**: <why this change fixes the root cause>
+
+## Validation
+- Syntax check: <pass/fail>
+- Type check: <pass/fail>
+- Diagnostics: <clean / N warnings>
+
+## Files Modified
+- <file1.ts>
+- <file2.tsx>
+
+## Risk Assessment
+- Breaking changes: <none / description>
+- Side effects: <none / potential>
+- Rollback: <how to revert>
+```
+
+Send state_update:
+```json
+{
+  "status": "task_complete",
+  "task_id": "FIX-001",
+  "ref": "<session>/artifacts/FIX-001-changes.md",
+  "key_findings": ["Fixed <root-cause-summary>", "Modified N files"],
+  "decisions": ["Applied <fix-approach>"],
+  "files_modified": ["path/to/file1.ts", "path/to/file2.tsx"],
+  "verification": "self-validated"
+}
+```
+
+## Error Handling
+
+| Scenario | Resolution |
+|----------|------------|
+| Source file not found | Search codebase, report if not found |
+| RCA location incorrect | Use ACE search to find correct location |
+| Syntax errors after fix | Iterate fix (max 3 attempts) |
+| Fix too complex | Report complexity, suggest manual intervention |
+| Multiple files need changes | Apply all changes, validate each |