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

feat(debugger): extract philosophy block to shared reference (#2363) (#2364)

Browse Source 
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 <noreply@anthropic.com>
This commit is contained in:
Tom Boucher
2026-04-17 10:23:18 -04:00
committed by GitHub
parent c2158b9690
commit 4a912e2e45
3 changed files with 80 additions and 72 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
CHANGELOG.md
View File

@@ -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 `<philosophy>` 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)

73
agents/gsd-debugger.md
View File

@@ -48,78 +48,7 @@ This ensures project-specific patterns, conventions, and best practices are appl
<philosophy>
## 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
</philosophy>

76
get-shit-done/references/debugger-philosophy.md Normal file
View File

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