# Lobster Debugging

> Lobster Debugging

- Skill: `comcclelland/lobster-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add comcclelland/lobster-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/comcclelland/lobster-debugging/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: comcclelland (https://skillmd.com/u/comcclelland)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/comcclelland/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