# Bug Debugger

> Use when a program fails, throws an exception, or behaves incorrectly and you need a systematic path to a root-cause fix.

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

---


# Bug Debugger

## When to use
- A test fails or the app crashes and the cause is not obvious.
- Behavior diverges from the documented contract.
- "It works on my machine" — reproducibility is the first problem.

## Workflow
1. **Reproduce reliably.** If you can't reproduce it on demand, you don't understand it.
   Capture the exact inputs, environment, and steps.
2. **Read the error, not the symptom.** Stack traces point at *where*, not *why*. Follow the
   call chain up to the first place the invariant was broken.
3. **Form one hypothesis**, then test it with the minimum change (a print, a breakpoint, a
   failing unit test). Avoid shotgun edits.
4. **Bisect if needed.** Comment out halves; use `git bisect` for regressions.
5. **Fix the root cause**, not the symptom. A `try/except pass` is almost never a fix.
6. **Add a regression test** that fails before the fix and passes after.

## Constraints
- Do not change behavior outside the bug's scope "while you're in there."
- Never silence an error without understanding it.
- Prefer the smallest change that restores the invariant.

## Definition of done
- The bug reproduces in a test that now passes.
- The fix is minimal and reviewed for side effects.
- No new warnings or flaky behavior were introduced.