diff --git a/agents/gsd-debugger.md b/agents/gsd-debugger.md index ecf37e78..4482062b 100644 --- a/agents/gsd-debugger.md +++ b/agents/gsd-debugger.md @@ -980,8 +980,14 @@ At investigation decision points, apply structured reasoning: - Run app/tests to observe behavior - APPEND to Evidence after each finding +**Phase 1.5: Check common bug patterns** +- Read @~/.claude/get-shit-done/references/common-bug-patterns.md +- Match symptoms to pattern categories using the Symptom-to-Category Quick Map +- Any matching patterns become hypothesis candidates for Phase 2 +- If no patterns match, proceed to open-ended hypothesis formation + **Phase 2: Form hypothesis** -- Based on evidence, form SPECIFIC, FALSIFIABLE hypothesis +- Based on evidence AND common pattern matches, form SPECIFIC, FALSIFIABLE hypothesis - Update Current Focus with hypothesis, test, expecting, next_action **Phase 3: Test hypothesis** diff --git a/get-shit-done/references/common-bug-patterns.md b/get-shit-done/references/common-bug-patterns.md new file mode 100644 index 00000000..5aae6260 --- /dev/null +++ b/get-shit-done/references/common-bug-patterns.md @@ -0,0 +1,114 @@ +# Common Bug Patterns + +Checklist of frequent bug patterns to scan before forming hypotheses. Ordered by frequency. Check these FIRST — they cover ~80% of bugs across all technology stacks. + + + +## Null / Undefined Access + +- [ ] Accessing property on `null` or `undefined` — missing null check or optional chaining +- [ ] Function returns `undefined` instead of expected value — missing `return` statement or wrong branch +- [ ] Array/object destructuring on `null`/`undefined` — API returned error shape instead of data +- [ ] Optional parameter used without default — caller omitted argument + +## Off-by-One / Boundary + +- [ ] Loop starts at 1 instead of 0, or ends at `length` instead of `length - 1` +- [ ] Fence-post error — "N items need N-1 separators" miscounted +- [ ] Inclusive vs exclusive range boundary — `<` vs `<=`, slice/substring end index +- [ ] Empty collection not handled — `.length === 0` falls through to logic assuming items exist + +## Async / Timing + +- [ ] Missing `await` on async function — gets Promise object instead of resolved value +- [ ] Race condition — two async operations read/write same state without coordination +- [ ] Stale closure — callback captures old variable value, not current one +- [ ] Event handler fires before setup complete — initialization order dependency +- [ ] Timeout/interval not cleaned up — fires after component/context destroyed + +## State Management + +- [ ] Mutating shared state — object/array modified in place affects other consumers +- [ ] State updated but UI not re-rendered — missing reactive trigger or wrong reference +- [ ] Stale state in event handler — closure captures state at bind time, not current value +- [ ] Multiple sources of truth — same data stored in two places, one gets out of sync +- [ ] State machine allows invalid transition — missing guard condition + +## Import / Module + +- [ ] Circular dependency — module A imports B, B imports A, one gets `undefined` +- [ ] Default vs named export mismatch — `import X` vs `import { X }` +- [ ] Wrong file extension — `.js` vs `.cjs` vs `.mjs`, `.ts` vs `.tsx` +- [ ] Path case sensitivity — works on Windows/macOS, fails on Linux +- [ ] Missing file extension in import — ESM requires explicit extensions + +## Type / Coercion + +- [ ] String vs number comparison — `"5" > "10"` is `true` (lexicographic), `5 > 10` is `false` +- [ ] Implicit type coercion — `==` instead of `===`, truthy/falsy surprises (`0`, `""`, `[]`) +- [ ] Integer overflow or floating point — `0.1 + 0.2 !== 0.3`, large numbers lose precision +- [ ] Boolean vs truthy check — value is `0` or `""` which is valid but falsy + +## Environment / Config + +- [ ] Environment variable missing or wrong — different value in dev vs prod vs CI +- [ ] Hardcoded path or URL — works on one machine, fails on another +- [ ] Port already in use — previous process still running +- [ ] File permission denied — different user/group in deployment +- [ ] Missing dependency — not in package.json or not installed + +## Data Shape / API Contract + +- [ ] API response shape changed — backend updated, frontend expects old format +- [ ] Array where object expected (or vice versa) — `data` vs `data.results` vs `data[0]` +- [ ] Missing field in payload — required field omitted, backend returns validation error +- [ ] Date/time format mismatch — ISO string vs timestamp vs locale string +- [ ] Encoding mismatch — UTF-8 vs Latin-1, URL encoding, HTML entities + +## Regex / String + +- [ ] Regex `g` flag with `.test()` then `.exec()` — `lastIndex` not reset between calls +- [ ] Missing escape — `.` matches any char, `$` is special, backslash needs doubling +- [ ] Greedy match captures too much — `.*` eats through delimiters, need `.*?` +- [ ] String interpolation in wrong quote type — template literals need backticks + +## Error Handling + +- [ ] Catch block swallows error — empty `catch {}` or logs but doesn't rethrow/handle +- [ ] Wrong error type caught — catches base `Error` when specific type needed +- [ ] Error in error handler — cleanup code throws, masking original error +- [ ] Promise rejection unhandled — missing `.catch()` or try/catch around `await` + +## Scope / Closure + +- [ ] Variable shadowing — inner scope declares same name, hides outer variable +- [ ] Loop variable capture — all closures share same `var i`, use `let` or bind +- [ ] `this` binding lost — callback loses context, need `.bind()` or arrow function +- [ ] Block scope vs function scope — `var` hoisted to function, `let`/`const` block-scoped + + + + + +## How to Use This Checklist + +1. **Before forming any hypothesis**, scan the relevant categories based on the symptom +2. **Match symptom to pattern** — if the bug involves "undefined is not an object", check Null/Undefined first +3. **Each checked pattern is a hypothesis candidate** — verify or eliminate with evidence +4. **If no pattern matches**, proceed to open-ended investigation + +### Symptom-to-Category Quick Map + +| Symptom | Check First | +|---------|------------| +| "Cannot read property of undefined/null" | Null/Undefined Access | +| "X is not a function" | Import/Module, Type/Coercion | +| Works sometimes, fails sometimes | Async/Timing, State Management | +| Works locally, fails in CI/prod | Environment/Config | +| Wrong data displayed | Data Shape, State Management | +| Off by one item / missing last item | Off-by-One/Boundary | +| "Unexpected token" / parse error | Data Shape, Type/Coercion | +| Memory leak / growing resource usage | Async/Timing (cleanup), Scope/Closure | +| Infinite loop / max call stack | State Management, Async/Timing | + +