Files
msd-core/get-shit-done/templates/debug-subagent-prompt.md
Lex Christopherson d498662938 feat: add parallel diagnosis before plan-fix
After UAT finds issues, spawn parallel debug agents to investigate
root causes before planning fixes. Each agent investigates one issue
with symptoms pre-filled from UAT, finds the root cause, and returns
diagnosis.

New files:
- workflows/diagnose-issues.md: Orchestrator for parallel debug agents
- templates/debug-subagent-prompt.md: Prompt template for debug subagents

Modified:
- workflows/debug.md: Add symptoms_prefilled and diagnose-only modes
- workflows/verify-work.md: Offer diagnosis step after issues found
- templates/UAT.md: Add root_cause and debug_session fields
- commands/gsd/plan-fix.md: Use root causes for targeted fix planning

Flow: UAT → diagnose (parallel) → plan-fix (with root causes) → execute

Co-Authored-By: Claude <noreply@anthropic.com>
2026-01-14 10:11:28 -06:00

4.1 KiB

Debug Subagent Prompt Template

Template for spawning debug agents from diagnose-issues workflow. Each agent investigates one UAT issue with symptoms pre-filled.


Template

<objective>
Investigate UAT issue and find root cause. Do NOT fix - only diagnose.

**Issue:** {issue_id}
**Summary:** {issue_summary}
**Severity:** {severity}

Symptoms are pre-filled from UAT testing. Skip symptom gathering, start investigating immediately.
</objective>

<execution_context>
@~/.claude/get-shit-done/workflows/debug.md
@~/.claude/get-shit-done/templates/DEBUG.md
@~/.claude/get-shit-done/references/debugging/debugging-mindset.md
@~/.claude/get-shit-done/references/debugging/hypothesis-testing.md
@~/.claude/get-shit-done/references/debugging/investigation-techniques.md
</execution_context>

<context>
**Symptoms (from UAT):**
- expected: {expected}
- actual: {reported}
- severity: {severity}
- reproduction: Test {test_num} in UAT

@.planning/STATE.md
@.planning/phases/{phase_dir}/{phase}-UAT.md
</context>

<mode>
**symptoms_prefilled: true**

Skip the symptom_gathering step entirely. Symptoms section is already filled.
Start directly at investigation_loop.

**goal: find_root_cause_only**

Do NOT apply fixes. Your job is to:
1. Investigate the issue
2. Form and test hypotheses
3. Find the root cause with evidence
4. Return the diagnosis

The fix will be planned and applied separately by /gsd:plan-fix.
</mode>

<debug_file>
Create: `.planning/debug/uat-{issue_id_lower}-{slug}.md`

Example: `.planning/debug/uat-001-comment-refresh.md`

Pre-fill Symptoms section:
```markdown
## Symptoms

expected: {expected}
actual: {reported}
errors: [investigate to find]
reproduction: Test {test_num} - {test_name}
started: discovered during UAT

Then proceed with investigation. </debug_file>

<return_format> When root cause is confirmed, return:

## DEBUG COMPLETE: {issue_id}

**Root Cause:** [specific cause with evidence]

**Evidence:**
- [key finding 1]
- [key finding 2]
- [key finding 3]

**Files Involved:**
- [file1.ts]: [what's wrong]
- [file2.ts]: [related issue]

**Debug Session:** .planning/debug/uat-{issue_id_lower}-{slug}.md

**Suggested Fix Direction:** [brief hint for plan-fix, not implementation]

If unable to determine root cause after thorough investigation:

## DEBUG INCONCLUSIVE: {issue_id}

**Investigation Summary:**
- [what was checked]
- [what was eliminated]

**Hypotheses Remaining:**
- [possible cause 1]
- [possible cause 2]

**Recommendation:** Manual review needed

**Debug Session:** .planning/debug/uat-{issue_id_lower}-{slug}.md

</return_format>

<success_criteria>

  • DEBUG-UAT-{NNN}.md created with symptoms pre-filled
  • Investigation completed (evidence gathered, hypotheses tested)
  • Root cause identified with supporting evidence
  • Debug session file updated throughout
  • Clear return format for orchestrator </success_criteria>

---

## Placeholders

| Placeholder | Source | Example |
|-------------|--------|---------|
| `{issue_id}` | UAT issue ID | `UAT-001` |
| `{issue_id_lower}` | Lowercase for filenames | `001` |
| `{issue_summary}` | Brief description | `Comment doesn't appear until refresh` |
| `{expected}` | From UAT test | `Submit comment, appears in list` |
| `{reported}` | User's description | `works but doesn't show until refresh` |
| `{severity}` | blocker/major/minor/cosmetic | `major` |
| `{test_num}` | Test number in UAT | `2` |
| `{test_name}` | Test name | `Create Top-Level Comment` |
| `{phase}` | Phase number | `04` |
| `{phase_dir}` | Phase directory name | `04-comments` |
| `{slug}` | Generated from summary | `comment-refresh` |

---

## Usage

Orchestrator (diagnose-issues.md) fills placeholders and spawns:

```python
# Spawn all debug agents in parallel
Task(prompt=filled_template_001, subagent_type="general-purpose", description="Debug UAT-001")
Task(prompt=filled_template_002, subagent_type="general-purpose", description="Debug UAT-002")
Task(prompt=filled_template_003, subagent_type="general-purpose", description="Debug UAT-003")

All agents run simultaneously. Each returns with root cause or inconclusive result.