diagnose-issues

name	diagnose-issues
description	Orchestrate parallel debug agents to investigate UAT gaps and find root causes. Spawns debug agents per gap, collects diagnoses, updates UAT.md.

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.

DEBUG_DIR=.gsd/debug

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

<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>

**Extract gaps from UAT.md:**

Read the "Gaps" section (YAML format):

- 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:

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

**Report diagnosis plan to user:**

## 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.

**Spawn debug agents in parallel:**

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

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

**Collect root causes from agents:**

Each agent returns with:

## 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

**Update UAT.md gaps with diagnosis:**

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

- 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:

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:

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

**Report diagnosis results and hand off:**

Display:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 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.

<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>