7.7 KiB
Context (pre-injected)
State:
Debugger Skills:
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.
<available_agent_types> Valid GSD subagent types (use exact names - do not fall back to 'general-purpose'):
- gsd-debugger - Diagnoses and fixes issues </available_agent_types>
Debug files use the .planning/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: "..."},
...
]
## 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.
AGENT_SKILLS_DEBUGGER=$(pi-gsd-tools agent-skills gsd-debugger 2>/dev/null)
Spawn debug agents in parallel:
For each gap, fill the debug-subagent-prompt template and spawn:
Task(
prompt=filled_debug_subagent_prompt + "\n\n<files_to_read>\n- {phase_dir}/{phase_num}-UAT.md\n- .planning/STATE.md\n</files_to_read>\n${AGENT_SKILLS_DEBUGGER}",
subagent_type="gsd-debugger",
isolation="worktree",
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
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
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: .planning/debug/comment-not-refreshing.md
Update status in frontmatter to "diagnosed".
Commit the updated UAT.md:
pi-gsd-tools commit "docs({phase_num}): add root causes from diagnosis" --files ".planning/phases/XX-name/{phase_num}-UAT.md"
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 /gsd-debug
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>