msd-core/get-shit-done/workflows/debug.md

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). 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:

• 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.**

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 @~/.claude/get-shit-done/templates/DEBUG.md

<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:

## 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

### 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.)

### 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

### 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:

## 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:

## 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):

## 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>

**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-fix to handle)

Default mode (no flags):

• Interactive debugging with user
• Gather symptoms through questions
• Investigate, fix, and verify

**First: Check for active debug sessions**

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).

mkdir -p ${DEBUG_DIR}

Create file with initial state:

---
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-fix 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".

mkdir -p ${DEBUG_RESOLVED_DIR}
mv ${DEBUG_DIR}/[slug].md ${DEBUG_RESOLVED_DIR}/

Commit:

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

<update_rules> 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. </update_rules>

<success_criteria>

• 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 </success_criteria>