From 759968de143232e99ba393efaa515b3d7cb92326 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 16:20:17 -0600 Subject: [PATCH] docs(13-02): deprecate workflows/debug.md - Replaced 665-line workflow with 14-line redirect - Points to agents/gsd-debugger.md for debugging expertise - Preserves git history while marking content as moved --- get-shit-done/workflows/debug.md | 668 +------------------------------ 1 file changed, 9 insertions(+), 659 deletions(-) diff --git a/get-shit-done/workflows/debug.md b/get-shit-done/workflows/debug.md index 79ce20576..d507a22c2 100644 --- a/get-shit-done/workflows/debug.md +++ b/get-shit-done/workflows/debug.md @@ -1,664 +1,14 @@ - -Systematic debugging with persistent state that survives context resets. The debug file IS the debugging brain - create it immediately and update it continuously. +# Debug Workflow (DEPRECATED) -You are the debugger. The user knows what's wrong (behavior), not why (root cause). Investigate autonomously. +This workflow has been consolidated into the `gsd-debugger` agent. -**Execution context:** -- **Subagent (typical):** Orchestrator gathered symptoms, you investigate with fresh 200k context -- **Main context (legacy):** Full interactive flow when not spawned as subagent +**Location:** `agents/gsd-debugger.md` -**Modes:** -- **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) - +**Reason:** The gsd-debugger agent contains all debugging expertise. Loading a separate workflow into orchestrator context was wasteful. - -DEBUG_DIR=.planning/debug -DEBUG_RESOLVED_DIR=.planning/debug/resolved +**Migration:** +- `/gsd:debug` now spawns `gsd-debugger` agent directly +- All debugging methodology lives in the agent file +- Templates remain at `get-shit-done/templates/DEBUG.md` -All debug files use the `.planning/debug/` path (hidden directory with leading dot). - - - -**User = reporter. Claude = investigator.** - -The user knows: -- What they expected to happen -- What actually happened -- Any error messages they saw -- When it started / if it ever worked - -The user does NOT know (and shouldn't be asked): -- What's causing the bug -- Which file has the problem -- What the fix should be - -Ask about experience. Investigate the cause yourself. - - - -@~/.claude/get-shit-done/references/debugging/debugging-mindset.md -@~/.claude/get-shit-done/references/debugging/hypothesis-testing.md -@~/.claude/get-shit-done/references/debugging/investigation-techniques.md -@~/.claude/get-shit-done/references/debugging/verification-patterns.md -@~/.claude/get-shit-done/references/debugging/when-to-research.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:** - -**symptoms_prefilled: true** -- Symptoms section already filled (from UAT or other source) -- Skip `symptom_gathering` step entirely -- Start directly at `investigation_loop` -- Create debug file with status: "investigating" (not "gathering") - -**goal: find_root_cause_only** -- Diagnose but don't fix -- Stop after confirming root cause -- Skip `fix_and_verify` step -- Return root cause to caller (for plan-phase --gaps to handle) - -**Default mode (no flags):** -- Interactive debugging with user -- Gather symptoms through questions -- Investigate, fix, and verify - - - - - -**First: Check for active debug sessions** - -```bash -ls ${DEBUG_DIR}/*.md 2>/dev/null | grep -v resolved -``` - -**If active sessions exist AND no $ARGUMENTS provided:** - -Read each file's frontmatter (status, trigger) and Current Focus (hypothesis, next_action). - -Display inline: - -``` -## Active Debug Sessions - -| # | Slug | Status | Hypothesis | Next Action | -|---|------|--------|------------|-------------| -| 1 | auth-logout | investigating | Token refresh not called | Check console output | -| 2 | api-timeout | gathering | - | Gather symptoms | -| 3 | cart-bug | fixing | Null reference in context | Apply fix | - -Reply with a number to resume, or describe a new issue to start fresh. -``` - -Wait for user response. - -- If user replies with number (1, 2, 3) → Load that file, go to `resume_from_file` -- If user replies with text → Treat as new issue trigger, go to `create_debug_file` - -**If active sessions exist AND $ARGUMENTS provided:** - -User wants to start a new debug session. Continue to `create_debug_file`. - -**If no active sessions AND no $ARGUMENTS:** - -``` -No active debug sessions. - -Describe the issue to start debugging. -``` - -Wait for user to describe the issue, then use their response as the trigger. - -**If no active sessions AND $ARGUMENTS provided:** - -Continue to `create_debug_file` with $ARGUMENTS as trigger. - - - -**Create debug file IMMEDIATELY** - -Generate slug from user input (lowercase, hyphens, max 30 chars). - -```bash -mkdir -p ${DEBUG_DIR} -``` - -Create file with initial state: - -```markdown ---- -status: gathering -trigger: "[verbatim $ARGUMENTS]" -created: [ISO timestamp] -updated: [ISO timestamp] ---- - -## Current Focus - -hypothesis: none yet -test: none -expecting: none -next_action: gather symptoms from user - -## Symptoms - -expected: -actual: -errors: -reproduction: -started: - -## Eliminated - -[none yet] - -## Evidence - -[none yet] - -## Resolution - -root_cause: -fix: -verification: -files_changed: [] -``` - -Write to `${DEBUG_DIR}/[slug].md` - -Now proceed to `symptom_gathering`. - - - -**Gather symptoms through questioning - update file after EACH answer** - -CRITICAL: Update the debug file after each piece of information gathered. - -**1. Expected behavior:** - -Use AskUserQuestion: -- header: "Expected" -- question: "What should happen?" -- options: Contextual interpretations + "Let me describe" - -After answer → Update Symptoms.expected in debug file - -**2. Actual behavior:** - -Use AskUserQuestion: -- header: "Actual" -- question: "What actually happens instead?" -- options: Common failure modes + "Let me describe" - -After answer → Update Symptoms.actual in debug file - -**3. Error messages:** - -Use AskUserQuestion: -- header: "Errors" -- question: "Any error messages?" -- options: - - "Yes, I'll paste them" - - "Yes, but I don't have them handy" - - "No errors - fails silently" - - "Not sure" - -After answer → Update Symptoms.errors in debug file - -**4. When it started:** - -Use AskUserQuestion: -- header: "Timeline" -- question: "When did this start?" -- options: - - "Never worked" - - "After a change" - - "Intermittent" - - "Not sure" - -After answer → Update Symptoms.started in debug file - -**5. Reproduction:** - -Use AskUserQuestion: -- header: "Reproduce" -- question: "How do you trigger this?" -- options: - - "Specific steps" - I can describe them - - "Random" - Happens unpredictably - - "Always" - Every time I try - - "Not sure" - -After answer → Update Symptoms.reproduction in debug file - -**6. Ready check:** - -Use AskUserQuestion: -- header: "Ready?" -- question: "Enough context to investigate?" -- options: - - "Start investigating" - - "I have more context" - -If "I have more context" → receive it, update relevant field, ask again -If "Start investigating" → Update status to "investigating", proceed to `investigation_loop` - - - -**Autonomous investigation - update file continuously** - -CRITICAL: Before EVERY action, update Current Focus. After EVERY finding, append to Evidence. - -**Phase 1: Initial evidence gathering** - -Update Current Focus: -``` -hypothesis: gathering initial evidence -test: examining error context and relevant code -expecting: clues about failure point -next_action: [specific next action] -``` - -1. If errors exist in Symptoms → search codebase for error text -2. Identify relevant code area from symptoms -3. Read relevant files COMPLETELY -4. Run app/tests to observe behavior firsthand - -After EACH finding → Append to Evidence: -``` -- timestamp: [now] - checked: [what] - found: [what] - implication: [what this means] -``` - -**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 the test. ONE hypothesis at a time. - -Append result to Evidence. - -**Phase 4: Evaluate** - -If CONFIRMED: -- Update Resolution.root_cause with evidence - -**If goal: find_root_cause_only:** -- Update status to "diagnosed" -- Proceed to `return_diagnosis` (skip fix_and_verify) - -**Otherwise (default):** -- Update status to "fixing" -- Proceed to `fix_and_verify` - -If ELIMINATED: -- Append to Eliminated section: - ``` - - hypothesis: [what was wrong] - evidence: [what disproved it] - timestamp: [now] - ``` -- Form new hypothesis based on evidence -- Return to Phase 2 - -**Context management:** - -After significant investigation (5+ evidence entries), check if context is heavy. -If so, ensure Current Focus is fully updated and suggest: -"Context filling up. Safe to /clear - run /gsd:debug to resume." - - - -**Resume investigation from debug file** - -Read the full debug file. - -Announce: -``` -Resuming: [slug] -Status: [status] -Current hypothesis: [from Current Focus] -Evidence gathered: [count] -Eliminated: [count] hypotheses - -Continuing from: [next_action] -``` - -Based on status: -- "gathering" → Continue `symptom_gathering` from where left off -- "investigating" → Continue `investigation_loop` from Current Focus -- "fixing" → Continue `fix_and_verify` -- "verifying" → Continue verification - -The file tells you exactly where you were. - - - -**Return root cause without fixing (diagnose-only mode)** - -This step is used when `goal: find_root_cause_only` is set (e.g., from diagnose-issues workflow). - -Update status to "diagnosed". - -Return structured diagnosis: - -``` -## DEBUG COMPLETE: {issue_id} - -**Root Cause:** {from Resolution.root_cause} - -**Evidence:** -{summary of key evidence entries} - -**Files Involved:** -{files identified during investigation} - -**Debug Session:** {path to debug file} - -**Suggested Fix Direction:** {brief hint based on root cause} -``` - -If unable to determine root cause after thorough investigation: - -``` -## DEBUG INCONCLUSIVE: {issue_id} - -**Investigation Summary:** -{what was checked} - -**Hypotheses Remaining:** -{possible causes not yet eliminated} - -**Recommendation:** Manual review needed - -**Debug Session:** {path to debug file} -``` - -**Do NOT proceed to fix_and_verify.** The fix will be planned by /gsd:plan-phase --gaps using this diagnosis. - - - -**Apply fix and verify** - -Update status to "fixing". - -**1. Implement minimal fix** - -Update Current Focus: -``` -hypothesis: [confirmed root cause] -test: applying fix -expecting: symptoms resolved -next_action: implement fix in [files] -``` - -Make the SMALLEST change that addresses root cause. - -Update Resolution.fix with what was changed and why. -Update Resolution.files_changed with modified files. - -**2. Verify** - -Update status to "verifying". - -Update Current Focus: -``` -hypothesis: fix resolves issue -test: reproducing original symptoms -expecting: symptoms no longer occur -next_action: verify fix -``` - -Test against original Symptoms: -- Does expected behavior now occur? -- Are errors gone? -- Does reproduction no longer trigger issue? - -If verification FAILS: -- Append finding to Evidence -- Update status back to "investigating" -- Root cause was wrong or incomplete -- Return to `investigation_loop` - -If verification PASSES: -- Update Resolution.verification with how verified -- Proceed to `archive_session` - - - -**Archive resolved debug session** - -Update status to "resolved". - -```bash -mkdir -p ${DEBUG_RESOLVED_DIR} -mv ${DEBUG_DIR}/[slug].md ${DEBUG_RESOLVED_DIR}/ -``` - -Commit: -```bash -git add -A -git commit -m "fix: [brief description from Resolution.fix] - -Root cause: [from Resolution.root_cause] -Debug session: ${DEBUG_RESOLVED_DIR}/[slug].md" -``` - -Report: -``` -Debug complete. - -Root cause: [root_cause] -Fix: [fix] -Files: [files_changed] - -Session archived: ${DEBUG_RESOLVED_DIR}/[slug].md -``` - -Use AskUserQuestion: -- header: "Next" -- question: "What now?" -- options: - - "Continue working" - Back to /gsd:progress - - "Test more" - Verify related functionality - - "Done" - End session - - - - - -**Section update rules (from template):** - -| Section | Rule | When | -|---------|------|------| -| Frontmatter.status | OVERWRITE | Each phase transition | -| Frontmatter.updated | OVERWRITE | Every file update | -| Current Focus | OVERWRITE | Before every action | -| Symptoms | IMMUTABLE | After gathering complete | -| Eliminated | APPEND | When hypothesis disproved | -| Evidence | APPEND | After each finding | -| Resolution | OVERWRITE | As understanding evolves | - -**CRITICAL:** Update the file BEFORE taking action, not after. If context resets mid-action, the file shows what was about to happen. - - - -- [ ] Debug file created IMMEDIATELY on command -- [ ] File updated after EACH piece of information -- [ ] Current Focus always reflects NOW -- [ ] Evidence appended for every finding -- [ ] Eliminated prevents re-investigation -- [ ] Can resume perfectly from any /clear -- [ ] Root cause confirmed with evidence before fixing -- [ ] Fix verified against original symptoms - +See `agents/gsd-debugger.md` for debugging expertise.