<purpose> Orchestrate parallel debug agents to investigate UAT gaps and find root causes.

After UAT finds gaps, spawn one debug agent per gap. Each agent investigates autonomously with symptoms pre-filled from UAT. Collect root causes, update UAT.md gaps with diagnosis, then hand off to plan-phase --gaps with actual diagnoses.

Orchestrator stays lean: parse gaps, spawn agents, collect results, update UAT. </purpose>

<paths> DEBUG_DIR=.gsd/debug

Debug files use the .gsd/debug/ path (hidden directory with leading dot). </paths>

<core_principle> Diagnose before planning fixes.

UAT tells us WHAT is broken (symptoms). Debug agents find WHY (root cause). plan-phase --gaps then creates targeted fixes based on actual causes, not guesses.

Without diagnosis: "Comment doesn't refresh" → guess at fix → maybe wrong With diagnosis: "Comment doesn't refresh" → "useEffect missing dependency" → precise fix </core_principle>

<process> <step name="parse_gaps"> **Extract gaps from UAT.md:**

Read the "Gaps" section (YAML format):

yaml

- truth: "Comment appears immediately after submission"
  status: failed
  reason: "User reported: works but doesn't show until I refresh the page"
  severity: major
  test: 2
  artifacts: []
  missing: []

For each gap, also read the corresponding test from "Tests" section to get full context.

Build gap list:

code

gaps = [
  {truth: "Comment appears immediately...", severity: "major", test_num: 2, reason: "..."},
  {truth: "Reply button positioned correctly...", severity: "minor", test_num: 5, reason: "..."},
  ...
]

</step> <step name="report_plan"> **Report diagnosis plan to user:**

code

## Diagnosing {N} Gaps

Spawning parallel debug agents to investigate root causes:

| Gap (Truth) | Severity |
|-------------|----------|
| Comment appears immediately after submission | major |
| Reply button positioned correctly | minor |
| Delete removes comment | blocker |

Each agent will:
1. Create DEBUG-{slug}.md with symptoms pre-filled
2. Investigate autonomously (read code, form hypotheses, test)
3. Return root cause

This runs in parallel - all gaps investigated simultaneously.

</step> <step name="spawn_agents"> **Spawn debug agents in parallel:**

For each gap, fill the debug-subagent-prompt template and spawn:

code

Task(
  prompt=filled_debug_subagent_prompt,
  subagent_type="general-purpose",
  description="Debug: {truth_short}"
)

All agents spawn in single message (parallel execution).

Template placeholders:

•{truth}: The expected behavior that failed
•{expected}: From UAT test
•{actual}: Verbatim user description from reason field
•{errors}: Any error messages from UAT (or "None reported")
•{reproduction}: "Test {test_num} in UAT"
•{timeline}: "Discovered during UAT"
•{goal}: find_root_cause_only (UAT flow - plan-phase --gaps handles fixes)
•{slug}: Generated from truth </step>

<step name="collect_results"> **Collect root causes from agents:**

Each agent returns with:

code

## ROOT CAUSE FOUND

**Debug Session:** ${DEBUG_DIR}/{slug}.md

**Root Cause:** {specific cause with evidence}

**Evidence Summary:**
- {key finding 1}
- {key finding 2}
- {key finding 3}

**Files Involved:**
- {file1}: {what's wrong}
- {file2}: {related issue}

**Suggested Fix Direction:** {brief hint for plan-phase --gaps}

Parse each return to extract:

•root_cause: The diagnosed cause
•files: Files involved
•debug_path: Path to debug session file
•suggested_fix: Hint for gap closure plan

If agent returns ## INVESTIGATION INCONCLUSIVE:

•root_cause: "Investigation inconclusive - manual review needed"
•Note which issue needs manual attention
•Include remaining possibilities from agent return </step>

<step name="update_uat"> **Update UAT.md gaps with diagnosis:**

For each gap in the Gaps section, add artifacts and missing fields:

yaml

- truth: "Comment appears immediately after submission"
  status: failed
  reason: "User reported: works but doesn't show until I refresh the page"
  severity: major
  test: 2
  root_cause: "useEffect in CommentList.tsx missing commentCount dependency"
  artifacts:
    - path: "src/components/CommentList.tsx"
      issue: "useEffect missing dependency"
  missing:
    - "Add commentCount to useEffect dependency array"
    - "Trigger re-render when new comment added"
  debug_session: .gsd/debug/comment-not-refreshing.md

Update status in frontmatter to "diagnosed".

Check planning config:

bash

COMMIT_PLANNING_DOCS=$(cat .gsd/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .gsd 2>/dev/null && COMMIT_PLANNING_DOCS=false

If COMMIT_PLANNING_DOCS=false: Skip git operations

If COMMIT_PLANNING_DOCS=true (default):

Commit the updated UAT.md:

bash

git add ".gsd/phases/XX-name/{phase}-UAT.md"
git commit -m "docs({phase}): add root causes from diagnosis"

</step> <step name="report_results"> **Report diagnosis results and hand off:**

Display:

code

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 GSD ► DIAGNOSIS COMPLETE
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

| Gap (Truth) | Root Cause | Files |
|-------------|------------|-------|
| Comment appears immediately | useEffect missing dependency | CommentList.tsx |
| Reply button positioned correctly | CSS flex order incorrect | ReplyButton.tsx |
| Delete removes comment | API missing auth header | api/comments.ts |

Debug sessions: ${DEBUG_DIR}/

Proceeding to plan fixes...

Return to verify-work orchestrator for automatic planning. Do NOT offer manual next steps - verify-work handles the rest. </step>

</process>

<context_efficiency> Agents start with symptoms pre-filled from UAT (no symptom gathering). Agents only diagnose—plan-phase --gaps handles fixes (no fix application). </context_efficiency>

<failure_handling> Agent fails to find root cause:

•Mark gap as "needs manual review"
•Continue with other gaps
•Report incomplete diagnosis

Agent times out:

•Check DEBUG-{slug}.md for partial progress
•Can resume with /debug.md

All agents fail:

•Something systemic (permissions, git, etc.)
•Report for manual investigation
•Fall back to plan-phase --gaps without root causes (less precise) </failure_handling>

<success_criteria>

• Gaps parsed from UAT.md
• Debug agents spawned in parallel
• Root causes collected from all agents
• UAT.md gaps updated with artifacts and missing
• Debug sessions saved to ${DEBUG_DIR}/
• Hand off to verify-work for automatic planning </success_criteria>