- name
- lobster-debugging
- version
- 1.0.0
- description
- Systematic debugging framework. 4-phase root-cause analysis with defense-in-depth. Never guess, never patch symptoms. From Claude Code + Superpowers.
- author
- Super Lobster 🦞
- tags
- ["debugging", "testing", "quality", "root-cause"]
- license
- MIT
Lobster Debugging 🦞
Systematic root-cause debugging. No guessing. No symptom patches. Ever.
The Iron Law
NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST4-Phase Process
Phase 1: Root Cause Investigation
- Read error messages completely (they often contain the solution)
- Reproduce consistently (can't fix what you can't reproduce)
- Check recent changes (git diff, recent commits)
- Add diagnostic instrumentation at component boundaries
- Binary search the codebase to isolate the failure point
Phase 2: Condition-Based Waiting
- Replace
sleep(5000)with event-based waiting - Wait for conditions, not timeouts
- Flaky tests = unfixed bug, not "timing issue"
Phase 3: Defense-in-Depth
- Fix the root cause
- Add a test that would have caught it
- Add a guard that prevents the class of bug
- Document why it happened
Phase 4: Academic Verification
- Prove the fix works with a test
- Prove the fix doesn't break anything else
- Prove the fix handles edge cases
- Prove the original bug can't recur
Red Flags — Stop and Re-Investigate
- "Just one quick fix" — there's no such thing
- Already tried multiple fixes — you don't understand the problem
- Under time pressure — rushing guarantees rework
- "Seems simple" — simple bugs have root causes too
When to Escalate
After 2 failed fix attempts:
- Stop. You're guessing.
- Go back to Phase 1.
- If still stuck, bring in a second agent with fresh context.