From 81c6c75b0e3a76829997b0ff1b515699764ed0d1 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 16:19:59 -0600 Subject: [PATCH] refactor(13-02): rewrite /gsd:debug as thin orchestrator - Reduced from 202 lines to 149 lines - Removed workflow/reference loading (expertise now in agent) - Uses subagent_type="gsd-debugger" instead of "general-purpose" - Keeps symptom gathering and checkpoint handling in orchestrator --- commands/gsd/debug.md | 172 +++++++++++++++--------------------------- 1 file changed, 60 insertions(+), 112 deletions(-) diff --git a/commands/gsd/debug.md b/commands/gsd/debug.md index 5471f106a..d01e22a68 100644 --- a/commands/gsd/debug.md +++ b/commands/gsd/debug.md @@ -4,33 +4,23 @@ description: Systematic debugging with persistent state across context resets argument-hint: [issue description] allowed-tools: - Read - - Write - - Edit - Bash - - Grep - - Glob - Task - AskUserQuestion --- -Debug issues using scientific method with subagent isolation for investigation. +Debug issues using scientific method with subagent isolation. -**Orchestrator role:** Gather symptoms interactively, spawn investigation subagent, handle checkpoints, spawn continuation agents as needed. +**Orchestrator role:** Gather symptoms, spawn gsd-debugger agent, handle checkpoints, spawn continuations. -**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation attempt. Main context stays lean for user interaction. +**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation. Main context stays lean for user interaction. - -@~/.claude/get-shit-done/workflows/debug.md -@~/.claude/get-shit-done/templates/DEBUG.md -@~/.claude/get-shit-done/templates/debug-subagent-prompt.md - - User's issue: $ARGUMENTS -Check for active debug sessions: +Check for active sessions: ```bash ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5 ``` @@ -47,7 +37,7 @@ If active sessions exist AND no $ARGUMENTS: If $ARGUMENTS provided OR user describes new issue: - Continue to symptom gathering -## 2. Gather Symptoms (Main Context) +## 2. Gather Symptoms (if new issue) Use AskUserQuestion for each: @@ -57,145 +47,103 @@ Use AskUserQuestion for each: 4. **Timeline** - When did this start? Ever worked? 5. **Reproduction** - How do you trigger it? -After each answer, note it. After all gathered, confirm ready to investigate. +After all gathered, confirm ready to investigate. -## 3. Create Debug File +## 3. Spawn gsd-debugger Agent -```bash -mkdir -p .planning/debug +Fill prompt and spawn: + +```markdown + +Investigate issue: {slug} + +**Summary:** {trigger} + + + +expected: {expected} +actual: {actual} +errors: {errors} +reproduction: {reproduction} +timeline: {timeline} + + + +symptoms_prefilled: true +goal: find_and_fix + + + +Create: .planning/debug/{slug}.md + ``` -Create `.planning/debug/{slug}.md` with: -- status: investigating -- trigger: user's original description -- Symptoms section filled from gathering -- Empty Evidence, Eliminated, Resolution sections - -## 4. Spawn Investigation Subagent - -Fill debug-subagent-prompt template with: -- `{slug}`: Generated slug -- `{trigger}`: Original issue description -- `{expected}`: From symptom gathering -- `{actual}`: From symptom gathering -- `{errors}`: From symptom gathering -- `{reproduction}`: From symptom gathering -- `{timeline}`: From symptom gathering - ``` Task( - prompt=filled_debug_subagent_prompt, - subagent_type="general-purpose", + prompt=filled_prompt, + subagent_type="gsd-debugger", description="Debug {slug}" ) ``` -## 5. Handle Subagent Return +## 4. Handle Agent Return **If `## ROOT CAUSE FOUND`:** - Display root cause and evidence summary - Offer options: - - "Fix now" → spawn fix subagent - - "Plan fix" → suggest /gsd:plan-phase --gaps - - "Manual fix" → done + - "Fix now" - spawn fix subagent + - "Plan fix" - suggest /gsd:plan-phase --gaps + - "Manual fix" - done **If `## CHECKPOINT REACHED`:** - Present checkpoint details to user - Get user response -- Spawn continuation agent (see step 6) +- Spawn continuation agent (see step 5) **If `## INVESTIGATION INCONCLUSIVE`:** - Show what was checked and eliminated - Offer options: - - "Continue investigating" → spawn new agent with additional context - - "Manual investigation" → done - - "Add more context" → gather more symptoms, spawn again + - "Continue investigating" - spawn new agent with additional context + - "Manual investigation" - done + - "Add more context" - gather more symptoms, spawn again -## 6. Spawn Continuation Agent (After Checkpoint) +## 5. Spawn Continuation Agent (After Checkpoint) When user responds to checkpoint, spawn fresh agent: ```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 - 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} - -@~/.claude/get-shit-done/workflows/debug.md -@~/.claude/get-shit-done/templates/DEBUG.md - - - -1. Read the debug file to understand current state -2. Incorporate user's checkpoint response -3. Continue investigation from Current Focus -4. Update debug file continuously -5. Return with ROOT CAUSE FOUND, CHECKPOINT REACHED, or INVESTIGATION INCONCLUSIVE - + +goal: find_and_fix + ``` -## 7. Fix (Optional) - -If user chooses "Fix now" after root cause found: - -```markdown - -Fix the root cause identified in {slug} debug session. - - - -Debug file: @.planning/debug/{slug}.md -Root cause: {root_cause} -Files involved: {files} - - - -1. Implement minimal fix addressing root cause -2. Verify fix against original symptoms -3. Update debug file Resolution section -4. Commit with message referencing debug session -5. Archive to .planning/debug/resolved/ - +``` +Task( + prompt=continuation_prompt, + subagent_type="gsd-debugger", + description="Continue debug {slug}" +) ``` - -Subagent may return checkpoints for: - -**human-verify:** "Can you confirm you see X when you do Y?" -- Present verification request -- User responds with confirmation or what they see instead - -**human-action:** "I need you to run this command / check this thing" -- Present action request -- User responds "done" or with results - -**decision:** "Should I investigate path A or path B?" -- Present options with context -- User picks direction - - -- [ ] Symptoms gathered interactively in main context -- [ ] Investigation runs in subagent (fresh context) -- [ ] Debug file tracks all state across agent boundaries -- [ ] Checkpoints handled via continuation agents -- [ ] Root cause confirmed with evidence before fixing -- [ ] Fix verified and session archived +- [ ] Active sessions checked +- [ ] Symptoms gathered (if new) +- [ ] gsd-debugger spawned with context +- [ ] Checkpoints handled correctly +- [ ] Root cause confirmed before fixing