golem15/msd-core
3
0
Fork 0
Code Issues Pull Requests Actions 1 Packages Projects Releases Wiki Activity

docs(13-02): deprecate workflows/debug.md

Browse Source 
- 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
This commit is contained in:
Lex Christopherson
2026-01-15 16:20:17 -06:00
parent 514ac2680f
commit 759968de14
1 changed files with 9 additions and 659 deletions
Download Patch File Download Diff File Expand all files Collapse all files

668
get-shit-done/workflows/debug.md
View File

@@ -1,664 +1,14 @@
<purpose>
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)
</purpose>
**Reason:** The gsd-debugger agent contains all debugging expertise. Loading a separate workflow into orchestrator context was wasteful.
<paths>
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).
</paths>
<philosophy>
**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.
</philosophy>
<references>
@~/.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
</references>
<template>
@~/.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:**
**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
</modes>
<process>
<step name="check_active_session">
**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.
</step>
<step name="create_debug_file">
**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`.
</step>
<step name="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`
</step>
<step name="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."
</step>
<step name="resume_from_file">
**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.
</step>
<step name="return_diagnosis">
**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.
</step>
<step name="fix_and_verify">
**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`
</step>
<step name="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
</step>
</process>
<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>
See `agents/gsd-debugger.md` for debugging expertise.