dream-zjk 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
- Reproduce reliably. If you can't reproduce it on demand, you don't understand it. Capture the exact inputs, environment, and steps.
- 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.
- Form one hypothesis, then test it with the minimum change (a print, a breakpoint, a failing unit test). Avoid shotgun edits.
- Bisect if needed. Comment out halves; use
git bisectfor regressions. - Fix the root cause, not the symptom. A
try/except passis almost never a fix. - 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.