From 4a912e2e45fe46e8e9fb219a81864a5eb817b42e Mon Sep 17 00:00:00 2001 From: Tom Boucher Date: Fri, 17 Apr 2026 10:23:18 -0400 Subject: [PATCH] feat(debugger): extract philosophy block to shared reference (#2363) (#2364) The gsd-debugger philosophy block contains 76 lines of evergreen debugging disciplines (user-as-reporter, meta-debugging, cognitive biases, restart protocol) that are not debugger-specific workflow and are paid in context on every debugger dispatch. Extracts to get-shit-done/references/debugger-philosophy.md, replaces the inline block with a single @file include. Behavior-preserving. Closes #2363 Co-authored-by: Claude Opus 4.7 --- CHANGELOG.md | 3 + agents/gsd-debugger.md | 73 +----------------- .../references/debugger-philosophy.md | 76 +++++++++++++++++++ 3 files changed, 80 insertions(+), 72 deletions(-) create mode 100644 get-shit-done/references/debugger-philosophy.md diff --git a/CHANGELOG.md b/CHANGELOG.md index b5bbfd13c..2d7d5a073 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,9 @@ Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/). ## [Unreleased] +### Changed +- **`gsd-debugger` philosophy extracted to shared reference** — The 76-line `` block containing evergreen debugging disciplines (user-as-reporter framing, meta-debugging, foundation principles, cognitive-bias table, systematic investigation, when-to-restart protocol) is now in `get-shit-done/references/debugger-philosophy.md` and pulled into the agent via a single `@file` include. Same content, lighter per-dispatch context footprint (#2363) + ### Fixed - **Shell hooks falsely flagged as stale on every session** — `gsd-phase-boundary.sh`, `gsd-session-state.sh`, and `gsd-validate-commit.sh` now ship with a `# gsd-hook-version: {{GSD_VERSION}}` header; the installer substitutes `{{GSD_VERSION}}` in `.sh` hooks the same way it does for `.js` hooks; and the stale-hook detector in `gsd-check-update.js` now matches bash `#` comment syntax in addition to JS `//` syntax. All three changes are required together — neither the regex fix alone nor the install fix alone is sufficient to resolve the false positive (#2136, #2206, #2209, #2210, #2212) diff --git a/agents/gsd-debugger.md b/agents/gsd-debugger.md index 4a2a5b16b..74a356a84 100644 --- a/agents/gsd-debugger.md +++ b/agents/gsd-debugger.md @@ -48,78 +48,7 @@ This ensures project-specific patterns, conventions, and best practices are appl -## User = Reporter, Claude = Investigator - -The user knows: -- What they expected to happen -- What actually happened -- Error messages they saw -- When it started / if it ever worked - -The user does NOT know (don't ask): -- What's causing the bug -- Which file has the problem -- What the fix should be - -Ask about experience. Investigate the cause yourself. - -## Meta-Debugging: Your Own Code - -When debugging code you wrote, you're fighting your own mental model. - -**Why this is harder:** -- You made the design decisions - they feel obviously correct -- You remember intent, not what you actually implemented -- Familiarity breeds blindness to bugs - -**The discipline:** -1. **Treat your code as foreign** - Read it as if someone else wrote it -2. **Question your design decisions** - Your implementation decisions are hypotheses, not facts -3. **Admit your mental model might be wrong** - The code's behavior is truth; your model is a guess -4. **Prioritize code you touched** - If you modified 100 lines and something breaks, those are prime suspects - -**The hardest admission:** "I implemented this wrong." Not "requirements were unclear" - YOU made an error. - -## Foundation Principles - -When debugging, return to foundational truths: - -- **What do you know for certain?** Observable facts, not assumptions -- **What are you assuming?** "This library should work this way" - have you verified? -- **Strip away everything you think you know.** Build understanding from observable facts. - -## Cognitive Biases to Avoid - -| Bias | Trap | Antidote | -|------|------|----------| -| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" | -| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating any | -| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise | -| **Sunk Cost** | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" | - -## Systematic Investigation Disciplines - -**Change one variable:** Make one change, test, observe, document, repeat. Multiple changes = no idea what mattered. - -**Complete reading:** Read entire functions, not just "relevant" lines. Read imports, config, tests. Skimming misses crucial details. - -**Embrace not knowing:** "I don't know why this fails" = good (now you can investigate). "It must be X" = dangerous (you've stopped thinking). - -## When to Restart - -Consider starting over when: -1. **2+ hours with no progress** - You're likely tunnel-visioned -2. **3+ "fixes" that didn't work** - Your mental model is wrong -3. **You can't explain the current behavior** - Don't add changes on top of confusion -4. **You're debugging the debugger** - Something fundamental is wrong -5. **The fix works but you don't know why** - This isn't fixed, this is luck - -**Restart protocol:** -1. Close all files and terminals -2. Write down what you know for certain -3. Write down what you've ruled out -4. List new hypotheses (different from before) -5. Begin again from Phase 1: Evidence Gathering +@~/.claude/get-shit-done/references/debugger-philosophy.md diff --git a/get-shit-done/references/debugger-philosophy.md b/get-shit-done/references/debugger-philosophy.md new file mode 100644 index 000000000..23ee967b8 --- /dev/null +++ b/get-shit-done/references/debugger-philosophy.md @@ -0,0 +1,76 @@ +# Debugger Philosophy + +Evergreen debugging disciplines — applies across every bug, every language, every system. Loaded by `gsd-debugger` via `@file` include. + +## User = Reporter, Claude = Investigator + +The user knows: +- What they expected to happen +- What actually happened +- Error messages they saw +- When it started / if it ever worked + +The user does NOT know (don't ask): +- What's causing the bug +- Which file has the problem +- What the fix should be + +Ask about experience. Investigate the cause yourself. + +## Meta-Debugging: Your Own Code + +When debugging code you wrote, you're fighting your own mental model. + +**Why this is harder:** +- You made the design decisions - they feel obviously correct +- You remember intent, not what you actually implemented +- Familiarity breeds blindness to bugs + +**The discipline:** +1. **Treat your code as foreign** - Read it as if someone else wrote it +2. **Question your design decisions** - Your implementation decisions are hypotheses, not facts +3. **Admit your mental model might be wrong** - The code's behavior is truth; your model is a guess +4. **Prioritize code you touched** - If you modified 100 lines and something breaks, those are prime suspects + +**The hardest admission:** "I implemented this wrong." Not "requirements were unclear" - YOU made an error. + +## Foundation Principles + +When debugging, return to foundational truths: + +- **What do you know for certain?** Observable facts, not assumptions +- **What are you assuming?** "This library should work this way" - have you verified? +- **Strip away everything you think you know.** Build understanding from observable facts. + +## Cognitive Biases to Avoid + +| Bias | Trap | Antidote | +|------|------|----------| +| **Confirmation** | Only look for evidence supporting your hypothesis | Actively seek disconfirming evidence. "What would prove me wrong?" | +| **Anchoring** | First explanation becomes your anchor | Generate 3+ independent hypotheses before investigating any | +| **Availability** | Recent bugs → assume similar cause | Treat each bug as novel until evidence suggests otherwise | +| **Sunk Cost** | Spent 2 hours on one path, keep going despite evidence | Every 30 min: "If I started fresh, is this still the path I'd take?" | + +## Systematic Investigation Disciplines + +**Change one variable:** Make one change, test, observe, document, repeat. Multiple changes = no idea what mattered. + +**Complete reading:** Read entire functions, not just "relevant" lines. Read imports, config, tests. Skimming misses crucial details. + +**Embrace not knowing:** "I don't know why this fails" = good (now you can investigate). "It must be X" = dangerous (you've stopped thinking). + +## When to Restart + +Consider starting over when: +1. **2+ hours with no progress** - You're likely tunnel-visioned +2. **3+ "fixes" that didn't work** - Your mental model is wrong +3. **You can't explain the current behavior** - Don't add changes on top of confusion +4. **You're debugging the debugger** - Something fundamental is wrong +5. **The fix works but you don't know why** - This isn't fixed, this is luck + +**Restart protocol:** +1. Close all files and terminals +2. Write down what you know for certain +3. Write down what you've ruled out +4. List new hypotheses (different from before) +5. Begin again from Phase 1: Evidence Gathering