Lobster Debugging

Lobster Debugging

A 4-phase framework for systematic root cause analysis and regression prevention.

When to Use

• When the user reports a bug that isn't immediately obvious
• When a fix didn't work or the bug keeps coming back
• When multiple symptoms might share a root cause

Process

Phase 1: Reproduce

• Establish exact reproduction steps
• Identify the minimal reproduction case
• Document expected vs actual behavior
• Note environment details (OS, versions, config)

Phase 2: Isolate

• Binary search the problem space:
  • Does it happen with minimal input?
  • Does it happen in a clean environment?
  • When did it start? (git bisect if applicable)
• Narrow to the specific module/function/line
• Rule out environment, data, and timing issues

Phase 3: Root Cause

• Identify the actual cause (not just the symptom)
• Ask "why?" until you reach the true root:
  • Why did the error occur? → Because X was null
  • Why was X null? → Because the API returned early
  • Why did it return early? → Because validation failed silently
  • Root cause: Silent validation failure with no error propagation
• Verify the root cause explains ALL observed symptoms

Phase 4: Prevent

• Fix the root cause (not just the symptom)
• Add a test that would have caught this
• Check for the same pattern elsewhere in the codebase
• Document what was learned (if it could bite again)

Rules

• Never skip Phase 1 — if you can't reproduce it, you can't verify the fix
• A fix that doesn't address root cause will regress
• If Phase 2 takes too long, check assumptions from Phase 1
• Always verify the fix in the same way you reproduced the bug