diff --git a/get-shit-done/templates/debug-subagent-prompt.md b/get-shit-done/templates/debug-subagent-prompt.md index 6a46a2c8d..c90c7ce45 100644 --- a/get-shit-done/templates/debug-subagent-prompt.md +++ b/get-shit-done/templates/debug-subagent-prompt.md @@ -1,10 +1,6 @@ # Debug Subagent Prompt Template -Template for spawning debug investigation agents. Used by: -- `/gsd:debug` — Interactive debugging (find and offer to fix) -- `diagnose-issues` — UAT parallel diagnosis (find root cause only) - -The `goal` flag determines behavior after root cause is found. +Template for spawning gsd-debugger agent. The agent contains all debugging expertise - this template provides problem context only. --- @@ -12,261 +8,27 @@ The `goal` flag determines behavior after root cause is found. ```markdown -Investigate issue and find root cause. +Investigate issue: {issue_id} -**Issue:** {issue_id} **Summary:** {issue_summary} - -Symptoms are pre-filled. Skip symptom gathering, start investigating immediately. - -@~/.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 - - -**Pre-filled from orchestrator:** - -- expected: {expected} -- actual: {actual} -- errors: {errors} -- reproduction: {reproduction} -- timeline: {timeline} - - - -**symptoms_prefilled: true** - -Skip the symptom_gathering step entirely. Symptoms section is already filled. -Start directly at investigation_loop. - -**goal: {goal}** - -- `find_root_cause_only` — Diagnose but do NOT fix. Return root cause to orchestrator. Used by UAT diagnosis flow where plan-phase --gaps handles the fix. -- `find_and_fix` — Find root cause, then fix and verify. Used by interactive /gsd:debug where user wants immediate resolution. - - - -**Path:** .planning/debug/{slug}.md - -Create debug file immediately with symptoms pre-filled: - -```markdown ---- -status: investigating -trigger: "{issue_summary}" -created: [ISO timestamp] -updated: [ISO timestamp] ---- - -## Current Focus - -hypothesis: gathering initial evidence -test: examining error context and relevant code -expecting: clues about failure point -next_action: search for error text in codebase - -## Symptoms - expected: {expected} actual: {actual} errors: {errors} reproduction: {reproduction} -started: {timeline} +timeline: {timeline} + -## Eliminated + +symptoms_prefilled: {true_or_false} +goal: {find_root_cause_only | find_and_fix} + -[none yet] - -## Evidence - -[none yet] - -## Resolution - -root_cause: -fix: -verification: -files_changed: [] -``` - -**Update continuously.** The debug file is your memory. Before every action, update Current Focus. After every finding, append to Evidence. + +Create: .planning/debug/{slug}.md - - -**When you need user input during investigation:** - -If you cannot proceed without user action or verification: - -1. Update debug file with current state -2. Return structured checkpoint instead of completing - -**Checkpoint format:** - -```markdown -## CHECKPOINT REACHED - -**Type:** [human-verify | human-action | decision] -**Debug Session:** .planning/debug/{slug}.md -**Progress:** {evidence_count} evidence entries, {eliminated_count} hypotheses eliminated - -### Investigation State - -**Current Hypothesis:** {from Current Focus} -**Evidence So Far:** -- {key finding 1} -- {key finding 2} - -### Checkpoint Details - -[Type-specific content] - -### Awaiting - -[What you need from user] -``` - -**Checkpoint types:** - -**human-verify** — Need user to confirm something you can't observe: -- What to check, how to check it, what to report back - -**human-action** — Need user to do something (auth, physical action): -- What action, why you can't do it, steps to complete - -**decision** — Need user to choose investigation direction: -- What's being decided, options with implications - -**After checkpoint:** Orchestrator gets user response, spawns fresh continuation agent. You will NOT be resumed. - - - -**Return ONE of these when done:** - ---- - -**Root cause found (goal: find_root_cause_only):** - -```markdown -## ROOT CAUSE FOUND - -**Debug Session:** .planning/debug/{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 gap closure plan, not implementation] -``` - ---- - -**Root cause found (goal: find_and_fix):** - -After finding root cause, proceed to fix_and_verify step per workflow. - -When complete: - -```markdown -## DEBUG COMPLETE - -**Debug Session:** .planning/debug/resolved/{slug}.md - -**Root Cause:** [what was wrong] -**Fix Applied:** [what was changed] -**Verification:** [how verified] - -**Files Changed:** -- [file1]: [change] -- [file2]: [change] - -**Commit:** [hash] -``` - ---- - -**Investigation inconclusive:** - -```markdown -## INVESTIGATION INCONCLUSIVE - -**Debug Session:** .planning/debug/{slug}.md - -**What Was Checked:** -- [area 1]: [finding] -- [area 2]: [finding] - -**Hypotheses Eliminated:** -- [hypothesis 1]: [why eliminated] -- [hypothesis 2]: [why eliminated] - -**Remaining Possibilities:** -- [possibility 1] -- [possibility 2] - -**Recommendation:** [next steps or manual review needed] -``` - - - -**Phase 1: Gather initial evidence** - -1. If errors in symptoms → search codebase for error text -2. Identify relevant code area from symptoms -3. Read relevant files COMPLETELY (don't skim) -4. Run app/tests to observe behavior firsthand - -After EACH finding → append to Evidence with timestamp, what was checked, what was found, implication. - -**Phase 2: Form hypothesis** - -Based on evidence, form SPECIFIC, FALSIFIABLE hypothesis. - -Update Current Focus: -- hypothesis: [specific theory] -- test: [how you'll test it] -- expecting: [what proves/disproves it] -- next_action: [immediate next step] - -**Phase 3: Test hypothesis** - -Execute ONE test at a time. Append result to Evidence. - -**Phase 4: Evaluate** - -If CONFIRMED: -- Update Resolution.root_cause with evidence -- If goal is find_root_cause_only → return ROOT CAUSE FOUND -- If goal is find_and_fix → proceed to fix_and_verify - -If ELIMINATED: -- Append to Eliminated section with evidence -- Form new hypothesis based on evidence -- Return to Phase 2 - -**If stuck:** Consider checkpoint to ask user for more context or verification. - - - -- [ ] Debug file created with symptoms pre-filled -- [ ] Current Focus updated before every action -- [ ] Evidence appended after every finding -- [ ] Hypotheses tested one at a time -- [ ] Root cause confirmed with evidence -- [ ] Appropriate return format based on goal -- [ ] Debug file reflects final state - ``` --- @@ -275,80 +37,55 @@ If ELIMINATED: | Placeholder | Source | Example | |-------------|--------|---------| -| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` or `UAT-001` | -| `{issue_summary}` | User description or UAT | `Auth screen is too dark` | -| `{expected}` | From symptoms | `See logo and form clearly` | -| `{actual}` | From symptoms | `Screen is dark, logo not visible` | +| `{issue_id}` | Orchestrator-assigned | `auth-screen-dark` | +| `{issue_summary}` | User description | `Auth screen is too dark` | +| `{expected}` | From symptoms | `See logo clearly` | +| `{actual}` | From symptoms | `Screen is dark` | | `{errors}` | From symptoms | `None in console` | | `{reproduction}` | From symptoms | `Open /auth page` | | `{timeline}` | From symptoms | `After recent deploy` | -| `{goal}` | Orchestrator sets | `find_and_fix` or `find_root_cause_only` | -| `{slug}` | Generated from summary | `auth-screen-dark` | +| `{goal}` | Orchestrator sets | `find_and_fix` | +| `{slug}` | Generated | `auth-screen-dark` | --- -## Usage by Orchestrator - -**From /gsd:debug (interactive):** +## Usage +**From /gsd:debug:** ```python Task( - prompt=filled_template, # goal: find_and_fix - subagent_type="general-purpose", + prompt=filled_template, + subagent_type="gsd-debugger", description="Debug {slug}" ) ``` -**From diagnose-issues (UAT parallel):** - +**From diagnose-issues (UAT):** ```python -# Spawn all in parallel -Task(prompt=template_001, subagent_type="general-purpose", description="Debug UAT-001") # goal: find_root_cause_only -Task(prompt=template_002, subagent_type="general-purpose", description="Debug UAT-002") -Task(prompt=template_003, subagent_type="general-purpose", description="Debug UAT-003") +Task(prompt=template, subagent_type="gsd-debugger", description="Debug UAT-001") ``` --- -## Continuation Agent +## Continuation -When orchestrator spawns fresh agent after checkpoint: +For checkpoints, spawn fresh agent with: ```markdown -Continue debugging {slug}. - -**DO NOT REDO** previous investigation. Evidence is in the debug file. +Continue debugging {slug}. Evidence is in the debug file. Debug file: @.planning/debug/{slug}.md - -Read this file first - it contains all evidence gathered so far. -**Checkpoint was:** {checkpoint_type} -**User response:** {user_response} - -{interpretation based on checkpoint type} +**Type:** {checkpoint_type} +**Response:** {user_response} -**goal: {goal}** +goal: {goal} - - -@~/.claude/get-shit-done/workflows/debug.md -@~/.claude/get-shit-done/templates/DEBUG.md -@~/.claude/get-shit-done/references/debugging/debugging-mindset.md - - - -1. Read debug file to understand current state -2. Incorporate user's checkpoint response into investigation -3. Continue from Current Focus -4. Update debug file continuously -5. Return with ROOT CAUSE FOUND, DEBUG COMPLETE, CHECKPOINT REACHED, or INVESTIGATION INCONCLUSIVE - ```