get-shit-done-cc 1.4.21 → 1.4.22

package/commands/gsd/debug.md

@@ -9,19 +9,22 @@ allowed-tools:
   - Bash
   - Grep
   - Glob
+  - Task
   - AskUserQuestion
 ---
 
 <objective>
-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.
 </objective>
 
 <execution_context>
 @~/.claude/get-shit-done/workflows/debug.md
 @~/.claude/get-shit-done/templates/DEBUG.md
+@~/.claude/get-shit-done/templates/debug-subagent-prompt.md
 </execution_context>
 
 <context>
@@ -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
 ```
 </context>
 
 <process>
-Follow the workflow in @~/.claude/get-shit-done/workflows/debug.md
 
-**Quick reference:**
+## 1. Check Active Sessions
+
+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
 
-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/`
+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
+<objective>
+Continue debugging {slug}.
+
+**DO NOT REDO** previous investigation. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+
+Read this file - it contains all evidence gathered so far.
+</prior_state>
+
+<checkpoint_response>
+**Checkpoint was:** {checkpoint_type}
+**User response:** {user_response}
+
+{interpretation based on checkpoint type}
+</checkpoint_response>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/debug.md
+@~/.claude/get-shit-done/templates/DEBUG.md
+</execution_context>
+
+<instructions>
+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
+</instructions>
+```
+
+## 7. Fix (Optional)
+
+If user chooses "Fix now" after root cause found:
+
+```markdown
+<objective>
+Fix the root cause identified in {slug} debug session.
+</objective>
+
+<context>
+Debug file: @.planning/debug/{slug}.md
+Root cause: {root_cause}
+Files involved: {files}
+</context>
+
+<instructions>
+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/
+</instructions>
+```
 
-**Key principle:** The DEBUG.md is your memory. Update it constantly. It survives `/clear`.
 </process>
 
+<checkpoint_types>
+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
+</checkpoint_types>
+
 <success_criteria>
-- [ ] 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
 </success_criteria>

package/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
 <objective>
-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.
 </objective>
 
 <execution_context>
@@ -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
 </execution_context>
 
-<context>
-**Symptoms (from UAT):**
-- expected: {expected}
-- actual: {reported}
-- severity: {severity}
-- reproduction: Test {test_num} in UAT
+<symptoms>
+**Pre-filled from orchestrator:**
 
-@.planning/STATE.md
-@.planning/phases/{phase_dir}/{phase}-UAT.md
-</context>
+- expected: {expected}
+- actual: {actual}
+- errors: {errors}
+- reproduction: {reproduction}
+- timeline: {timeline}
+</symptoms>
 
 <mode>
 **symptoms_prefilled: true**
@@ -42,86 +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**
-
-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
+**goal: {goal}**
 
-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.
 </mode>
 
 <debug_file>
-Create: `.planning/debug/{slug}.md`
+**Path:** .planning/debug/{slug}.md
 
-Generate slug from issue summary (same as regular /gsd:debug).
-Example: `comment-not-refreshing.md`
+Create debug file immediately with symptoms pre-filled:
 
-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
 
-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.
+[none yet]
 
-Then proceed with investigation.
+## 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.
 </debug_file>
 
-<return_format>
-When root cause is confirmed, return:
+<checkpoint_behavior>
+**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.
+</checkpoint_behavior>
+
+<return_formats>
+**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:** .planning/debug/{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:** .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]
 ```
-</return_format>
+</return_formats>
+
+<investigation_protocol>
+**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.
+</investigation_protocol>
 
 <success_criteria>
 - [ ] 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
 </success_criteria>
 ```
 
@@ -131,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
+
+**From /gsd:debug (interactive):**
+
+```python
+Task(
+  prompt=filled_template,  # goal: find_and_fix
+  subagent_type="general-purpose",
+  description="Debug {slug}"
+)
+```
 
-Orchestrator (diagnose-issues.md) fills placeholders and spawns:
+**From diagnose-issues (UAT parallel):**
 
 ```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")
+# 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")
 ```
 
-All agents run simultaneously. Each returns with root cause or inconclusive result.
+---
+
+## Continuation Agent
+
+When orchestrator spawns fresh agent after checkpoint:
+
+```markdown
+<objective>
+Continue debugging {slug}.
+
+**DO NOT REDO** previous investigation. Evidence is in the debug file.
+</objective>
+
+<prior_state>
+Debug file: @.planning/debug/{slug}.md
+
+Read this file first - it contains all evidence gathered so far.
+</prior_state>
+
+<checkpoint_response>
+**Checkpoint was:** {checkpoint_type}
+**User response:** {user_response}
+
+{interpretation based on checkpoint type}
+</checkpoint_response>
+
+<mode>
+**goal: {goal}**
+</mode>
+
+<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
+</execution_context>
+
+<instructions>
+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
+</instructions>
+```

package/get-shit-done/workflows/debug.md

@@ -1,14 +1,25 @@
 <purpose>
 Systematic debugging with persistent state that survives context resets. The debug file IS the debugging brain - create it immediately and update it continuously.
 
-You are the debugger. The user knows what's wrong (behavior), not why (root cause). Gather symptoms, then investigate autonomously.
+You are the debugger. The user knows what's wrong (behavior), not why (root cause). Investigate autonomously.
+
+**Execution context:**
+- **Subagent (typical):** Orchestrator gathered symptoms, you investigate with fresh 200k context
+- **Main context (legacy):** Full interactive flow when not spawned as subagent
 
 **Modes:**
-- **Interactive (default):** User reports issue, gather symptoms through questions, investigate, fix
-- **Symptoms prefilled:** Symptoms provided (e.g., from UAT), skip gathering, start investigating immediately
-- **Diagnose only:** Find root cause but don't fix (for parallel diagnosis before plan-fix)
+- **symptoms_prefilled: true** — Symptoms provided, start investigating immediately
+- **goal: find_root_cause_only** — Diagnose but don't fix, return to caller
+- **goal: find_and_fix** — Find root cause, fix it, verify (default)
 </purpose>
 
+<paths>
+DEBUG_DIR=.planning/debug
+DEBUG_RESOLVED_DIR=.planning/debug/resolved
+
+All debug files use the `.planning/debug/` path (hidden directory with leading dot).
+</paths>
+
 <philosophy>
 **User = reporter. Claude = investigator.**
 
@@ -38,6 +49,157 @@ Ask about experience. Investigate the cause yourself.
 @~/.claude/get-shit-done/templates/DEBUG.md
 </template>
 
+<checkpoint_behavior>
+**When running as subagent and you need user input:**
+
+If investigation requires user action or verification that you cannot perform:
+
+1. **Update debug file** with current state (Current Focus, Evidence so far)
+2. **Return structured checkpoint** instead of completing
+
+**Checkpoint return 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 - see below]
+
+### Awaiting
+
+[What you need from user]
+```
+
+**Checkpoint types:**
+
+**human-verify:** Need user to confirm something you can't observe
+```markdown
+### Checkpoint Details
+
+**Need verification:** {what you need confirmed}
+
+**How to check:**
+1. {step 1}
+2. {step 2}
+
+**Tell me:** {what to report back}
+
+### Awaiting
+
+Describe what you see, or "confirmed" / "not seeing it"
+```
+
+**human-action:** Need user to do something (auth, physical action, etc.)
+```markdown
+### Checkpoint Details
+
+**Action needed:** {what user must do}
+
+**Why:** {why you can't do it}
+
+**Steps:**
+1. {step 1}
+2. {step 2}
+
+### Awaiting
+
+Type "done" when complete
+```
+
+**decision:** Need user to choose investigation direction
+```markdown
+### Checkpoint Details
+
+**Decision needed:** {what's being decided}
+
+**Context:** {why this matters for investigation}
+
+**Options:**
+- **A:** {option and implications}
+- **B:** {option and implications}
+
+### Awaiting
+
+Reply with A or B (or describe alternative)
+```
+
+**After checkpoint:** Orchestrator presents to user, gets response, spawns fresh continuation agent with your debug file + user response. You will NOT be resumed.
+</checkpoint_behavior>
+
+<structured_returns>
+**When investigation completes, return one of these:**
+
+**Root cause found:**
+```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:** {brief direction, not implementation}
+```
+
+**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}
+```
+
+**Fix complete (when goal is find_and_fix):**
+```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}
+```
+</structured_returns>
+
 <modes>
 **Check for mode flags in prompt context:**
 
@@ -65,7 +227,7 @@ Ask about experience. Investigate the cause yourself.
 **First: Check for active debug sessions**
 
 ```bash
-ls .planning/debug/*.md 2>/dev/null | grep -v resolved
+ls ${DEBUG_DIR}/*.md 2>/dev/null | grep -v resolved
 ```
 
 **If active sessions exist AND no $ARGUMENTS provided:**
@@ -116,7 +278,7 @@ Continue to `create_debug_file` with $ARGUMENTS as trigger.
 Generate slug from user input (lowercase, hyphens, max 30 chars).
 
 ```bash
-mkdir -p .planning/debug
+mkdir -p ${DEBUG_DIR}
 ```
 
 Create file with initial state:
@@ -160,7 +322,7 @@ verification:
 files_changed: []
 ```
 
-Write to `.planning/debug/[slug].md`
+Write to `${DEBUG_DIR}/[slug].md`
 
 Now proceed to `symptom_gathering`.
 </step>
@@ -439,8 +601,8 @@ If verification PASSES:
 Update status to "resolved".
 
 ```bash
-mkdir -p .planning/debug/resolved
-mv .planning/debug/[slug].md .planning/debug/resolved/
+mkdir -p ${DEBUG_RESOLVED_DIR}
+mv ${DEBUG_DIR}/[slug].md ${DEBUG_RESOLVED_DIR}/
 ```
 
 Commit:
@@ -449,7 +611,7 @@ git add -A
 git commit -m "fix: [brief description from Resolution.fix]
 
 Root cause: [from Resolution.root_cause]
-Debug session: .planning/debug/resolved/[slug].md"
+Debug session: ${DEBUG_RESOLVED_DIR}/[slug].md"
 ```
 
 Report:
@@ -460,7 +622,7 @@ Root cause: [root_cause]
 Fix: [fix]
 Files: [files_changed]
 
-Session archived: .planning/debug/resolved/[slug].md
+Session archived: ${DEBUG_RESOLVED_DIR}/[slug].md
 ```
 
 Use AskUserQuestion:

package/get-shit-done/workflows/diagnose-issues.md

@@ -6,6 +6,12 @@ After UAT finds issues, spawn one debug agent per issue. Each agent investigates
 Orchestrator stays lean: parse issues, spawn agents, collect results, update UAT.
 </purpose>
 
+<paths>
+DEBUG_DIR=.planning/debug
+
+Debug files use the `.planning/debug/` path (hidden directory with leading dot).
+</paths>
+
 <core_principle>
 **Diagnose before planning fixes.**
 
@@ -84,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
 </step>
 
 <step name="collect_results">
@@ -95,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:** .planning/debug/{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
 </step>
 
 <step name="update_uat">
@@ -128,7 +145,7 @@ result: issue
 reported: "works but doesn't show until I refresh the page"
 severity: major
 root_cause: "useEffect in CommentList.tsx missing commentCount dependency - doesn't re-render when new comment added"
-debug_session: .planning/debug/comment-not-refreshing.md
+debug_session: ${DEBUG_DIR}/comment-not-refreshing.md
 ```
 
 Update the "Issues for /gsd:plan-fix" section with root causes:
@@ -165,7 +182,7 @@ git commit -m "docs({phase}): add root causes from diagnosis"
 | UAT-002 | CSS flex order incorrect | ReplyButton.tsx |
 | UAT-003 | API missing auth header | api/comments.ts |
 
-Debug sessions saved to .planning/debug/
+Debug sessions saved to ${DEBUG_DIR}/
 
 ---
 
@@ -228,6 +245,6 @@ The fix plan will use diagnosed root causes for targeted fixes.
 - [ ] Debug agents spawned in parallel
 - [ ] Root causes collected from all agents
 - [ ] UAT.md updated with root causes
-- [ ] Debug sessions saved to .planning/debug/
+- [ ] Debug sessions saved to ${DEBUG_DIR}/
 - [ ] User knows next steps (plan-fix)
 </success_criteria>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "get-shit-done-cc",
-  "version": "1.4.21",
+  "version": "1.4.22",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "get-shit-done-cc": "bin/install.js"