fix(debug): add DEBUG_DIR path constant to prevent typos

Define DEBUG_DIR=.planning/debug at top of debug-related files.
Reference ${DEBUG_DIR} throughout to reduce path typo risk.

Co-Authored-By: Claude <noreply@anthropic.com>

get-shit-done/templates/debug-subagent-prompt.md

@@ -54,10 +54,12 @@ The fix will be planned and applied separately by /gsd:plan-fix.
 </mode>
 
 <debug_file>
-Create: `.planning/debug/{slug}.md`
+**Path constant:** DEBUG_DIR=.planning/debug
+
+Create: `${DEBUG_DIR}/{slug}.md`
 
 Generate slug from issue summary (same as regular /gsd:debug).
-Example: `comment-not-refreshing.md`
+Example: `.planning/debug/comment-not-refreshing.md`
 
 Pre-fill Symptoms section:
 ```markdown
@@ -92,7 +94,7 @@ When root cause is confirmed, return:
 - [file1.ts]: [what's wrong]
 - [file2.ts]: [related issue]
 
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
 
 **Suggested Fix Direction:** [brief hint for plan-fix, not implementation]
 ```
@@ -112,7 +114,7 @@ If unable to determine root cause after thorough investigation:
 
 **Recommendation:** Manual review needed
 
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
 ```
 </return_format>
 

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:

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.**
 
@@ -99,7 +105,7 @@ Each agent returns with:
 
 **Root Cause:** {specific cause with evidence}
 **Files Involved:** {list of files}
-**Debug Session:** .planning/debug/{slug}.md
+**Debug Session:** ${DEBUG_DIR}/{slug}.md
 
 **Evidence Summary:**
 - {key finding 1}
@@ -128,7 +134,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 +171,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 +234,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>