From 00208b71afcd3a39f8047c81b8592589ef2a7dc5 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 14 Jan 2026 10:59:59 -0600 Subject: [PATCH] feat(debug): subagent isolation for investigation with checkpoint support - Debug command now orchestrates: gather symptoms in main context, spawn investigation subagent with fresh 200k context - Subagent template unified for both /gsd:debug (find_and_fix) and diagnose-issues (find_root_cause_only) flows via goal flag - Checkpoint behavior enables subagent to pause for user input (human-verify, human-action, decision) with continuation agents - Structured return formats: ROOT CAUSE FOUND, DEBUG COMPLETE, INVESTIGATION INCONCLUSIVE, CHECKPOINT REACHED - diagnose-issues updated to match new template placeholders and returns Co-Authored-By: Claude --- commands/gsd/debug.md | 177 ++++++++- .../templates/debug-subagent-prompt.md | 342 ++++++++++++++---- get-shit-done/workflows/diagnose-issues.md | 29 +- 3 files changed, 448 insertions(+), 100 deletions(-) diff --git a/commands/gsd/debug.md b/commands/gsd/debug.md index 0d3c9f6a6..573f7af73 100644 --- a/commands/gsd/debug.md +++ b/commands/gsd/debug.md @@ -9,19 +9,22 @@ allowed-tools: - Bash - Grep - Glob + - Task - AskUserQuestion --- -Debug issues using scientific method with a persistent debug document that survives `/clear`. +Debug issues using scientific method with subagent isolation for investigation. -If resuming (no arguments and active session exists): pick up where you left off. -If starting new: gather symptoms, then investigate autonomously. +**Orchestrator role:** Gather symptoms interactively, spawn investigation subagent, handle checkpoints, spawn continuation agents as needed. + +**Why subagent:** Investigation burns context fast (reading files, forming hypotheses, testing). Fresh 200k context per investigation attempt. 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 @@ -29,30 +32,170 @@ User's issue: $ARGUMENTS Check for active debug sessions: ```bash -ls .planning/debug/*.md 2>/dev/null | head -5 +ls .planning/debug/*.md 2>/dev/null | grep -v resolved | head -5 ``` -Follow the workflow in @~/.claude/get-shit-done/workflows/debug.md -**Quick reference:** +## 1. Check Active Sessions -1. **Check for active sessions** - Offer to resume or start new -2. **Gather symptoms** - What happened? What should happen? Errors? When? -3. **Create DEBUG.md** - Document symptoms in `.planning/debug/[slug].md` -4. **Investigate** - Evidence → Hypothesis → Test → Eliminate or Confirm -5. **Fix and verify** - Minimal fix, verify against original symptoms -6. **Archive** - Move to `.planning/debug/resolved/` +If active sessions exist AND no $ARGUMENTS: +- List sessions with status, hypothesis, next action +- User picks number to resume OR describes new issue + +If $ARGUMENTS provided OR user describes new issue: +- Continue to symptom gathering + +## 2. Gather Symptoms (Main Context) + +Use AskUserQuestion for each: + +1. **Expected behavior** - What should happen? +2. **Actual behavior** - What happens instead? +3. **Error messages** - Any errors? (paste or describe) +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. + +## 3. Create Debug File + +```bash +mkdir -p .planning/debug +``` + +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", + description="Debug {slug}" +) +``` + +## 5. Handle Subagent Return + +**If `## ROOT CAUSE FOUND`:** +- Display root cause and evidence summary +- Offer options: + - "Fix now" → spawn fix subagent + - "Plan fix" → suggest /gsd:plan-fix + - "Manual fix" → done + +**If `## CHECKPOINT REACHED`:** +- Present checkpoint details to user +- Get user response +- Spawn continuation agent (see step 6) + +**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 + +## 6. 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. + + + +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} + + + +@~/.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 + +``` + +## 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/ + +``` -**Key principle:** The DEBUG.md is your memory. Update it constantly. It survives `/clear`. + +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 + + -- [ ] Active sessions checked before starting new -- [ ] Symptoms gathered through AskUserQuestion (not inline questions) -- [ ] DEBUG.md tracks all investigation state -- [ ] Scientific method followed (not random fixes) +- [ ] 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 diff --git a/get-shit-done/templates/debug-subagent-prompt.md b/get-shit-done/templates/debug-subagent-prompt.md index bfb565357..6b0895517 100644 --- a/get-shit-done/templates/debug-subagent-prompt.md +++ b/get-shit-done/templates/debug-subagent-prompt.md @@ -1,6 +1,10 @@ # Debug Subagent Prompt Template -Template for spawning debug agents from diagnose-issues workflow. Each agent investigates one UAT issue with symptoms pre-filled. +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. --- @@ -8,13 +12,12 @@ Template for spawning debug agents from diagnose-issues workflow. Each agent inv ```markdown -Investigate UAT issue and find root cause. Do NOT fix - only diagnose. +Investigate issue and find root cause. **Issue:** {issue_id} **Summary:** {issue_summary} -**Severity:** {severity} -Symptoms are pre-filled from UAT testing. Skip symptom gathering, start investigating immediately. +Symptoms are pre-filled. Skip symptom gathering, start investigating immediately. @@ -25,16 +28,15 @@ Symptoms are pre-filled from UAT testing. Skip symptom gathering, start investig @~/.claude/get-shit-done/references/debugging/investigation-techniques.md - -**Symptoms (from UAT):** -- expected: {expected} -- actual: {reported} -- severity: {severity} -- reproduction: Test {test_num} in UAT + +**Pre-filled from orchestrator:** -@.planning/STATE.md -@.planning/phases/{phase_dir}/{phase}-UAT.md - +- expected: {expected} +- actual: {actual} +- errors: {errors} +- reproduction: {reproduction} +- timeline: {timeline} + **symptoms_prefilled: true** @@ -42,88 +44,228 @@ Symptoms are pre-filled from UAT testing. Skip symptom gathering, start investig Skip the symptom_gathering step entirely. Symptoms section is already filled. Start directly at investigation_loop. -**goal: find_root_cause_only** +**goal: {goal}** -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. +- `find_root_cause_only` — Diagnose but do NOT fix. Return root cause to orchestrator. Used by UAT diagnosis flow where plan-fix handles the fix. +- `find_and_fix` — Find root cause, then fix and verify. Used by interactive /gsd:debug where user wants immediate resolution. -**Path constant:** DEBUG_DIR=.planning/debug +**Path:** .planning/debug/{slug}.md -Create: `${DEBUG_DIR}/{slug}.md` +Create debug file immediately with symptoms pre-filled: -Generate slug from issue summary (same as regular /gsd:debug). -Example: `.planning/debug/comment-not-refreshing.md` - -Pre-fill Symptoms section: ```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: {reported} -errors: [investigate to find] -reproduction: Test {test_num} - {test_name} -started: discovered during UAT +actual: {actual} +errors: {errors} +reproduction: {reproduction} +started: {timeline} + +## Eliminated + +[none yet] + +## Evidence + +[none yet] + +## Resolution + +root_cause: +fix: +verification: +files_changed: [] ``` -The debug file is identical to a regular debug session. The only difference is symptoms are pre-filled. UAT.md tracks the link via `debug_session` field. - -Then proceed with investigation. +**Update continuously.** The debug file is your memory. Before every action, update Current Focus. After every finding, append to Evidence. - -When root cause is confirmed, return: + +**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] ``` -## DEBUG COMPLETE: {issue_id} + +**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:** +**Evidence Summary:** - [key finding 1] - [key finding 2] - [key finding 3] **Files Involved:** -- [file1.ts]: [what's wrong] -- [file2.ts]: [related issue] - -**Debug Session:** ${DEBUG_DIR}/{slug}.md +- [file1]: [what's wrong] +- [file2]: [related issue] **Suggested Fix Direction:** [brief hint for plan-fix, not implementation] ``` -If unable to determine root cause after thorough investigation: +--- +**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] ``` -## DEBUG INCONCLUSIVE: {issue_id} -**Investigation Summary:** -- [what was checked] -- [what was eliminated] +--- -**Hypotheses Remaining:** -- [possible cause 1] -- [possible cause 2] +**Investigation inconclusive:** -**Recommendation:** Manual review needed +```markdown +## INVESTIGATION INCONCLUSIVE -**Debug Session:** ${DEBUG_DIR}/{slug}.md +**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 -- [ ] Investigation completed (evidence gathered, hypotheses tested) -- [ ] Root cause identified with supporting evidence -- [ ] Debug session file updated throughout -- [ ] Clear return format for orchestrator +- [ ] 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 ``` @@ -133,28 +275,80 @@ If unable to determine root cause after thorough investigation: | Placeholder | Source | Example | |-------------|--------|---------| -| `{issue_id}` | UAT issue ID | `UAT-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-not-refreshing` | +| `{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` | +| `{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` | --- -## Usage +## Usage by Orchestrator -Orchestrator (diagnose-issues.md) fills placeholders and spawns: +**From /gsd:debug (interactive):** ```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") +Task( + prompt=filled_template, # goal: find_and_fix + subagent_type="general-purpose", + description="Debug {slug}" +) ``` -All agents run simultaneously. Each returns with root cause or inconclusive result. +**From diagnose-issues (UAT parallel):** + +```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") +``` + +--- + +## Continuation Agent + +When orchestrator spawns fresh agent after checkpoint: + +```markdown + +Continue debugging {slug}. + +**DO NOT REDO** previous investigation. 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} + + + +**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 + +``` diff --git a/get-shit-done/workflows/diagnose-issues.md b/get-shit-done/workflows/diagnose-issues.md index 66942a7ad..3bff02bdd 100644 --- a/get-shit-done/workflows/diagnose-issues.md +++ b/get-shit-done/workflows/diagnose-issues.md @@ -90,10 +90,12 @@ Template placeholders: - `{issue_id}`: UAT-001, UAT-002, etc. - `{issue_summary}`: Brief description - `{expected}`: From UAT test -- `{reported}`: Verbatim user description -- `{severity}`: blocker/major/minor/cosmetic -- `{phase}`: Phase being tested -- `{phase_dir}`: Path to phase directory +- `{actual}`: Verbatim user description (what actually happened) +- `{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-fix handles fixes) +- `{slug}`: Generated from issue_summary @@ -101,25 +103,34 @@ Template placeholders: Each agent returns with: ``` -## DEBUG COMPLETE: UAT-{NNN} +## ROOT CAUSE FOUND + +**Debug Session:** ${DEBUG_DIR}/{slug}.md **Root Cause:** {specific cause with evidence} -**Files Involved:** {list of files} -**Debug Session:** ${DEBUG_DIR}/{slug}.md **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-fix} ``` Parse each return to extract: - root_cause: The diagnosed cause - files: Files involved -- debug_path: Path to debug session file (standard debug location) +- debug_path: Path to debug session file +- suggested_fix: Hint for plan-fix -If agent fails or can't determine root cause: +If agent returns `## INVESTIGATION INCONCLUSIVE`: - root_cause: "Investigation inconclusive - manual review needed" - Note which issue needs manual attention +- Include remaining possibilities from agent return