Systematic Debugging
Never "fix" something that has not been reproduced. Work the steps below in order; do not skip ahead to a fix, however obvious the cause looks.
1. Reproduce first
State the reproduction:
- The exact action that triggers the bug (command, request, input, click path).
- What happens, versus what should happen.
Then run the reproduction and confirm the failure yourself. If the environment does not allow running it, say so and ask the user for the failing output — never proceed on an assumed failure mode.
If the bug cannot be reproduced, stop. Report what was tried and what extra information would make it reproducible.
2. Isolate
Narrow down where the failure lives before deciding why it happens:
- Change one variable at a time: one input, one config value, one commit, one layer.
- Cut the search space in half where possible: does the bad value already exist at the API boundary? In the database? In the request? Use
git bisect for regressions; shrink a failing input to the smallest that still fails.
- State what has been ruled out as you go, so nothing gets re-tested.
3. Hypothesize with evidence
Every hypothesis needs an observation that could falsify it, gathered before the fix:
- State the hypothesis: "X fails because Y."
- Name the check that would disprove it: a log line, a debugger value, a targeted test, a smaller reproduction.
- Run the check. If the observation contradicts the hypothesis, discard it and say so; do not stretch the hypothesis to fit.
Reading code and concluding "this must be it" is not evidence — the check must observe the running system.
4. Fix and confirm
- Make the smallest change that addresses the confirmed cause. Do not refactor, clean up, or fix unrelated issues in the same pass; note them for later.
- Confirm the fix against the original reproduction from step 1, not only by passing tests.
- Run the project's test suite to check for regressions, and add a test that captures the reproduction.
Reporting
At each step, state which one you are on and what was observed. If a fix attempt fails, report the failure and return to step 3 with the new observation; do not stack a second guess on top of the first.
1---2name: systematic-debugging3description: Diagnose bugs, failing tests, or unexpected behavior by reproducing, isolating, hypothesizing with evidence, and confirming fixes before making changes.4---56# Systematic Debugging78Never "fix" something that has not been reproduced. Work the steps below in order; do not skip ahead to a fix, however obvious the cause looks.910## 1. Reproduce first1112State the reproduction:1314- The exact action that triggers the bug (command, request, input, click path).15- What happens, versus what should happen.1617Then run the reproduction and confirm the failure yourself. If the environment does not allow running it, say so and ask the user for the failing output — never proceed on an assumed failure mode.1819If the bug cannot be reproduced, stop. Report what was tried and what extra information would make it reproducible.2021## 2. Isolate2223Narrow down where the failure lives before deciding why it happens:2425- Change one variable at a time: one input, one config value, one commit, one layer.26- Cut the search space in half where possible: does the bad value already exist at the API boundary? In the database? In the request? Use `git bisect` for regressions; shrink a failing input to the smallest that still fails.27- State what has been ruled out as you go, so nothing gets re-tested.2829## 3. Hypothesize with evidence3031Every hypothesis needs an observation that could falsify it, gathered before the fix:3233- State the hypothesis: "X fails because Y."34- Name the check that would disprove it: a log line, a debugger value, a targeted test, a smaller reproduction.35- Run the check. If the observation contradicts the hypothesis, discard it and say so; do not stretch the hypothesis to fit.3637Reading code and concluding "this must be it" is not evidence — the check must observe the running system.3839## 4. Fix and confirm4041- Make the smallest change that addresses the confirmed cause. Do not refactor, clean up, or fix unrelated issues in the same pass; note them for later.42- Confirm the fix against the original reproduction from step 1, not only by passing tests.43- Run the project's test suite to check for regressions, and add a test that captures the reproduction.4445## Reporting4647At each step, state which one you are on and what was observed. If a fix attempt fails, report the failure and return to step 3 with the new observation; do not stack a second guess on top of the first.
NagareNegishi