# Systematic Debugging

> Systematic approach to debugging — follow these 8 steps when investigating bugs, errors, or unexpected behavior

- Skill: `subinium/systematic-debugging` (Agent Skill)
- Install (CLI): `npx skillmds@latest add subinium/systematic-debugging`
- Raw SKILL.md: https://api.skillmd.com/api/skills/subinium/systematic-debugging/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: subinium (https://skillmd.com/u/subinium)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/subinium/systematic-debugging

---


# Systematic Debugging

Follow these steps in strict order. Do not skip ahead.

## Steps

### 1. Reproduce
- Get the exact error message and full stack trace
- Find the minimal reproduction case
- Confirm you can trigger the error consistently

### 2. Isolate
- Narrow down to the smallest failing unit
- Binary search: comment out half the code, check which half fails
- Check if the issue is in your code vs dependencies

### 3. Trace
- Follow data flow from input to the error point
- Log actual values at each step (don't assume)
- Check types at runtime, not just static analysis

### 4. Hypothesize
- Form at most 3 specific, testable theories
- Rank by likelihood
- Each hypothesis must predict a specific observable outcome

### 5. Test
- Test ONE hypothesis at a time
- Make the smallest possible change to verify
- If wrong, revert before testing the next hypothesis

### 6. Fix
- Apply the smallest correct fix
- Ensure the fix addresses the root cause, not the symptom
- Check for the same bug pattern elsewhere in the codebase

### 7. Verify
- Run the exact test that exposed the bug
- Run related tests to check for regressions
- Test edge cases around the fix

### 8. Prevent
- Add a regression test if one doesn't exist
- Consider if a type constraint or assertion could prevent recurrence
- Document if the root cause was non-obvious

## Anti-Patterns (Never Do These)
- Shotgun debugging: changing multiple things at once
- Guessing without tracing actual values
- Fixing symptoms instead of root causes
- Skipping the verification step
- Adding try/catch to hide errors instead of fixing them