get-shit-done-cc 1.4.2 → 1.4.4

package/README.md

@@ -344,6 +344,7 @@ You're never locked in. The system adapts.
 | `/gsd:consider-issues` | Review deferred issues, close resolved, identify urgent |
 | `/gsd:add-todo [desc]` | Capture idea or task from conversation for later |
 | `/gsd:check-todos [area]` | List pending todos, select one to work on |
+| `/gsd:debug [desc]` | Systematic debugging with persistent state across `/clear` |
 | `/gsd:help` | Show all commands and usage guide |
 
 <sup>¹ Contributed by reddit user OracleGreyBeard</sup>

package/commands/gsd/debug.md

@@ -0,0 +1,58 @@
+---
+name: gsd:debug
+description: Systematic debugging with persistent state across context resets
+argument-hint: [issue description]
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Grep
+  - Glob
+  - AskUserQuestion
+---
+
+<objective>
+Debug issues using scientific method with a persistent debug document that survives `/clear`.
+
+If resuming (no arguments and active session exists): pick up where you left off.
+If starting new: gather symptoms, then investigate autonomously.
+</objective>
+
+<execution_context>
+@~/.claude/get-shit-done/workflows/debug.md
+@~/.claude/get-shit-done/templates/DEBUG.md
+</execution_context>
+
+<context>
+User's issue: $ARGUMENTS
+
+Check for active debug sessions:
+```bash
+ls .planning/debug/*.md 2>/dev/null | head -5
+```
+</context>
+
+<process>
+Follow the workflow in @~/.claude/get-shit-done/workflows/debug.md
+
+**Quick reference:**
+
+1. **Check for active sessions** - Offer to resume or start new
+2. **Gather symptoms** - What happened? What should happen? Errors? When?
+3. **Create DEBUG.md** - Document symptoms in `.planning/debug/[slug].md`
+4. **Investigate** - Evidence → Hypothesis → Test → Eliminate or Confirm
+5. **Fix and verify** - Minimal fix, verify against original symptoms
+6. **Archive** - Move to `.planning/debug/resolved/`
+
+**Key principle:** The DEBUG.md is your memory. Update it constantly. It survives `/clear`.
+</process>
+
+<success_criteria>
+- [ ] Active sessions checked before starting new
+- [ ] Symptoms gathered through AskUserQuestion (not inline questions)
+- [ ] DEBUG.md tracks all investigation state
+- [ ] Scientific method followed (not random fixes)
+- [ ] Root cause confirmed with evidence before fixing
+- [ ] Fix verified and session archived
+</success_criteria>

package/commands/gsd/help.md

@@ -248,6 +248,20 @@ Review deferred issues with codebase context.
 
 Usage: `/gsd:consider-issues`
 
+### Debugging
+
+**`/gsd:debug [issue description]`**
+Systematic debugging with persistent state across context resets.
+
+- Gathers symptoms through adaptive questioning
+- Creates `.planning/debug/[slug].md` to track investigation
+- Investigates using scientific method (evidence → hypothesis → test)
+- Survives `/clear` — run `/gsd:debug` with no args to resume
+- Archives resolved issues to `.planning/debug/resolved/`
+
+Usage: `/gsd:debug "login button doesn't work"`
+Usage: `/gsd:debug` (resume active session)
+
 ### Todo Management
 
 **`/gsd:add-todo [description]`**
@@ -291,6 +305,8 @@ Show this command reference.
 ├── todos/                # Captured ideas and tasks
 │   ├── pending/          # Todos waiting to be worked on
 │   └── done/             # Completed todos
+├── debug/                # Active debug sessions
+│   └── resolved/         # Archived resolved issues
 ├── codebase/             # Codebase map (brownfield projects)
 │   ├── STACK.md          # Languages, frameworks, dependencies
 │   ├── ARCHITECTURE.md   # Patterns, layers, data flow
@@ -367,6 +383,15 @@ Change anytime by editing `.planning/config.json`
 /gsd:check-todos api             # Filter by area
 ```
 
+**Debugging an issue:**
+
+```
+/gsd:debug "form submission fails silently"  # Start debug session
+# ... investigation happens, context fills up ...
+/clear
+/gsd:debug                                    # Resume from where you left off
+```
+
 ## Getting Help
 
 - Read `.planning/PROJECT.md` for project vision

package/commands/gsd/progress.md

@@ -58,6 +58,7 @@ If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd:
 - Note any blockers, concerns, or deferred issues
 - Check for CONTEXT.md: For phases without PLAN.md files, check if `{phase}-CONTEXT.md` exists in phase directory
 - Count pending todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
+- Check for active debug sessions: `ls .planning/debug/*.md 2>/dev/null | grep -v resolved | wc -l`
   </step>
 
 <step name="report">
@@ -87,6 +88,10 @@ CONTEXT: [✓ if CONTEXT.md exists | - if not]
 ## Pending Todos
 - [count] pending — /gsd:check-todos to review
 
+## Active Debug Sessions
+- [count] active — /gsd:debug to continue
+(Only show this section if count > 0)
+
 ## What's Next
 [Next phase/plan objective from ROADMAP]
 ```

package/get-shit-done/references/debugging/debugging-mindset.md

@@ -0,0 +1,253 @@
+<philosophy>
+Debugging is applied epistemology. You're investigating a system to discover truth about its behavior. The difference between junior and senior debugging is not knowledge of frameworks - it's the discipline of systematic investigation.
+</philosophy>
+
+<meta_debugging>
+**Special challenge**: When you're debugging code you wrote or modified, you're fighting your own mental model.
+
+**Why this is harder**:
+- You made the design decisions - they feel obviously correct
+- You remember your intent, not what you actually implemented
+- You see what you meant to write, not what's there
+- Familiarity breeds blindness to bugs
+
+**The trap**:
+- "I know this works because I implemented it correctly"
+- "The bug must be elsewhere - I designed this part"
+- "I tested this approach"
+- These thoughts are red flags. Code you wrote is guilty until proven innocent.
+
+**The discipline**:
+
+**1. Treat your own code as foreign**
+- Read it as if someone else wrote it
+- Don't assume it does what you intended
+- Verify what it actually does, not what you think it does
+- Fresh eyes see bugs; familiar eyes see intent
+
+**2. Question your own design decisions**
+- "I chose approach X because..." - Was that reasoning sound?
+- "I assumed Y would..." - Have you verified Y actually does that?
+- Your implementation decisions are hypotheses, not facts
+
+**3. Admit your mental model might be wrong**
+- You built a mental model of how this works
+- That model might be incomplete or incorrect
+- The code's behavior is truth; your model is just a guess
+- Be willing to discover you misunderstood the problem
+
+**4. Prioritize code you touched**
+- If you modified 100 lines and something breaks
+- Those 100 lines are the prime suspects
+- Don't assume the bug is in the framework or existing code
+- Start investigating where you made changes
+
+<example>
+❌ "I implemented the auth flow correctly, the bug must be in the existing user service"
+
+✅ "I implemented the auth flow. Let me verify each part:
+   - Does login actually set the token? [test it]
+   - Does the middleware actually validate it? [test it]
+   - Does logout actually clear it? [test it]
+   - One of these is probably wrong"
+
+The second approach found that logout wasn't clearing the token from localStorage, only from memory.
+</example>
+
+**The hardest admission**: "I implemented this wrong."
+
+Not "the requirements were unclear" or "the library is confusing" - YOU made an error. Whether it was 5 minutes ago or 5 days ago doesn't matter. Your code, your responsibility, your bug to find.
+
+This intellectual honesty is the difference between debugging for hours and finding bugs quickly.
+</meta_debugging>
+
+<foundation>
+When debugging, return to foundational truths:
+
+**What do you know for certain?**
+- What have you directly observed (not assumed)?
+- What can you prove with a test right now?
+- What is speculation vs evidence?
+
+**What are you assuming?**
+- "This library should work this way" - Have you verified?
+- "The docs say X" - Have you tested that X actually happens?
+- "This worked before" - Can you prove when it worked and what changed?
+
+Strip away everything you think you know. Build understanding from observable facts.
+</foundation>
+
+<example>
+❌ "React state updates should be synchronous here"
+✅ "Let me add a console.log to observe when state actually updates"
+
+❌ "The API must be returning bad data"
+✅ "Let me log the exact response payload to see what's actually being returned"
+
+❌ "This database query should be fast"
+✅ "Let me run EXPLAIN to see the actual execution plan"
+</example>
+
+<cognitive_biases>
+
+<bias name="confirmation_bias">
+**The problem**: You form a hypothesis and only look for evidence that confirms it.
+
+**The trap**: "I think it's a race condition" → You only look for async code, missing the actual typo in a variable name.
+
+**The antidote**: Actively seek evidence that disproves your hypothesis. Ask "What would prove me wrong?"
+</bias>
+
+<bias name="anchoring">
+**The problem**: The first explanation you encounter becomes your anchor, and you adjust from there instead of considering alternatives.
+
+**The trap**: Error message mentions "timeout" → You assume it's a network issue, when it's actually a deadlock.
+
+**The antidote**: Generate multiple independent hypotheses before investigating any single one. Force yourself to list 3+ possible causes.
+</bias>
+
+<bias name="availability_heuristic">
+**The problem**: You remember recent bugs and assume similar symptoms mean the same cause.
+
+**The trap**: "We had a caching issue last week, this must be caching too."
+
+**The antidote**: Treat each bug as novel until evidence suggests otherwise. Recent memory is not evidence.
+</bias>
+
+<bias name="sunk_cost_fallacy">
+**The problem**: You've spent 2 hours debugging down one path, so you keep going even when evidence suggests it's wrong.
+
+**The trap**: "I've almost figured out this state management issue" - when the actual bug is in the API layer.
+
+**The antidote**: Set checkpoints. Every 30 minutes, ask: "If I started fresh right now, is this still the path I'd take?"
+</bias>
+
+</cognitive_biases>
+
+<systematic_investigation>
+
+<discipline name="change_one_variable">
+**Why it matters**: If you change multiple things at once, you don't know which one fixed (or broke) it.
+
+**In practice**:
+1. Make one change
+2. Test
+3. Observe result
+4. Document
+5. Repeat
+
+**The temptation**: "Let me also update this dependency and refactor this function and change this config..."
+
+**The reality**: Now you have no idea what actually mattered.
+</discipline>
+
+<discipline name="complete_reading">
+**Why it matters**: Skimming code causes you to miss crucial details. You see what you expect to see, not what's there.
+
+**In practice**:
+- Read entire functions, not just the "relevant" lines
+- Read imports and dependencies
+- Read configuration files completely
+- Read test files to understand intended behavior
+
+**The shortcut**: "This function is long, I'll just read the part where the error happens"
+
+**The miss**: The bug is actually in how the function is called 50 lines up.
+</discipline>
+
+<discipline name="embrace_not_knowing">
+**Why it matters**: Premature certainty stops investigation. "I don't know" is a position of strength.
+
+**In practice**:
+- "I don't know why this fails" - Good. Now you can investigate.
+- "It must be X" - Dangerous. You've stopped thinking.
+
+**The pressure**: Users want answers. Managers want ETAs. Your ego wants to look smart.
+
+**The truth**: "I need to investigate further" is more professional than a wrong fix.
+</discipline>
+
+</systematic_investigation>
+
+<when_to_restart>
+
+<restart_signals>
+You should consider starting over when:
+
+1. **You've been investigating for 2+ hours with no progress**
+   - You're likely tunnel-visioned
+   - Take a break, then restart from evidence gathering
+
+2. **You've made 3+ "fixes" that didn't work**
+   - Your mental model is wrong
+   - Go back to first principles
+
+3. **You can't explain the current behavior**
+   - Don't add more changes on top of confusion
+   - First understand what's happening, then fix it
+
+4. **You're debugging the debugger**
+   - "Is my logging broken? Is the debugger lying?"
+   - Step back. Something fundamental is wrong.
+
+5. **The fix works but you don't know why**
+   - This isn't fixed. This is luck.
+   - Investigate until you understand, or revert the change
+</restart_signals>
+
+<restart_protocol>
+When restarting:
+
+1. **Close all files and terminals**
+2. **Write down what you know for certain** (not what you think)
+3. **Write down what you've ruled out**
+4. **List new hypotheses** (different from before)
+5. **Begin again from Phase 1: Evidence Gathering**
+
+This isn't failure. This is professionalism.
+</restart_protocol>
+
+</when_to_restart>
+
+<humility>
+The best debuggers have deep humility about their mental models:
+
+**They know**:
+- Their understanding of the system is incomplete
+- Documentation can be wrong or outdated
+- Their memory of "how this works" may be faulty
+- The system's behavior is the only truth
+
+**They don't**:
+- Trust their first instinct
+- Assume anything works as designed
+- Skip verification steps
+- Declare victory without proof
+
+**They ask**:
+- "What am I missing?"
+- "What am I wrong about?"
+- "What haven't I tested?"
+- "What does the evidence actually say?"
+</humility>
+
+<craft>
+Debugging is a craft that improves with practice:
+
+**Novice debuggers**:
+- Try random things hoping something works
+- Skip reading code carefully
+- Don't test their hypotheses
+- Declare success too early
+
+**Expert debuggers**:
+- Form hypotheses explicitly
+- Test hypotheses systematically
+- Read code like literature
+- Verify fixes rigorously
+- Learn from each investigation
+
+**The difference**: Not intelligence. Not knowledge. Discipline.
+
+Practice the discipline of systematic investigation, and debugging becomes a strength.
+</craft>