From b1066c1f3c89c5edfed7f5fa8fca5545ea22ba88 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Wed, 14 Jan 2026 10:51:25 -0600 Subject: [PATCH] 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 --- .../templates/debug-subagent-prompt.md | 10 +- get-shit-done/workflows/debug.md | 184 ++++++++++++++++-- get-shit-done/workflows/diagnose-issues.md | 14 +- 3 files changed, 189 insertions(+), 19 deletions(-) diff --git a/get-shit-done/templates/debug-subagent-prompt.md b/get-shit-done/templates/debug-subagent-prompt.md index a59188f61..bfb565357 100644 --- a/get-shit-done/templates/debug-subagent-prompt.md +++ b/get-shit-done/templates/debug-subagent-prompt.md @@ -54,10 +54,12 @@ The fix will be planned and applied separately by /gsd:plan-fix. -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 ``` diff --git a/get-shit-done/workflows/debug.md b/get-shit-done/workflows/debug.md index d3d834780..729bdd6d4 100644 --- a/get-shit-done/workflows/debug.md +++ b/get-shit-done/workflows/debug.md @@ -1,14 +1,25 @@ 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) + +DEBUG_DIR=.planning/debug +DEBUG_RESOLVED_DIR=.planning/debug/resolved + +All debug files use the `.planning/debug/` path (hidden directory with leading dot). + + **User = reporter. Claude = investigator.** @@ -38,6 +49,157 @@ Ask about experience. Investigate the cause yourself. @~/.claude/get-shit-done/templates/DEBUG.md + +**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. + + + +**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} +``` + + **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`. @@ -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: diff --git a/get-shit-done/workflows/diagnose-issues.md b/get-shit-done/workflows/diagnose-issues.md index b87630c79..66942a7ad 100644 --- a/get-shit-done/workflows/diagnose-issues.md +++ b/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. + +DEBUG_DIR=.planning/debug + +Debug files use the `.planning/debug/` path (hidden directory with leading dot). + + **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)