debugging-systematicallylisted

# Debugging systematically Guessing is expensive. Every guess costs a run, and a wrong guess that happens to make the symptom go away leaves the bug in place. Work down this list instead. ## 1. Reproduce it Find the shortest command that fails, every time, and write it down. If you cannot reproduce it, you cannot fix it — say so and go get what you need: the exact input, the log, the version, the steps. A bug report with no reproduction is a question, not a task. If it only fails sometimes, run it in a loop and record the failure rate. "Flaky" is a measurement, not a diagnosis — order dependence, a real race, a clock, and a shared fixture all look the same until you count. ## 2. Read the actual error The whole stack trace, the first failure rather than the last, and the line it names. Most of the time the answer is in the output you skimmed past. ## 3. Narrow it Cut the search space in half, repeatedly: - **In the code:** delete or stub out half the path. Does it still fail? - **In history:** if it used to work, `git log` the files involved and `git bisect` if the range is wide. A commit is a very short explanation. - **In the data:** shrink the input until removing one more thing makes the failure disappear. Stop when you have the smallest case that still fails. That case is your test. ## 4. Prove the cause Before you change anything, be able to finish this sentence: "it fails because X, and I know that because Y." If Y is "it seemed likely", you are still gues