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