Debugging is not guessing with extra steps; it's a search problem, and a search problem has a systematic solution: understand the space you're searching, reproduce the failure on demand, shrink the search space by half at a time, and change exactly one thing per experiment so cause and effect stay unambiguous. Every rule below traces back to Agans' Debugging: The 9 Indispensable Rules; treat them as a sequence, not a menu to pick from.

Redact secrets before showing any command, log, or captured artifact: same discipline as 's Phase 3: replace credentials with , quote only the lines carrying real signal from anything with auth headers or full payloads.

Before touching anything, know the normal path the failing code should take: read or equivalent domain docs if they exist, trace the flow from entry point to the point of failure, and know what "correct" looks like well enough to recognize it. A theory formed without this is a guess with the system's real shape substituted by an assumed one.

Reproduce on demand first. A bug that only happens "sometimes, somewhere in prod" isn't diagnosable yet; build the smallest repeatable trigger: a failing test, a script, a request replayed against a dev instance. For a flaky/non-deterministic failure, the goal isn't a clean 100% repro but a high enough reproduction rate to observe: loop it, add stress, narrow timing windows, until it fails often enough to study.

Then look, don't theorize. With a reproducible failure in hand, inspect the actual evidence (logs, state, a debugger breakpoint) before forming a hypothesis. A theory built by staring at code without first looking at what the system actually did is the single most common way to burn time chasing the wrong cause.

Shrink the suspect region by bisecting it, not by scanning it linearly:

Each bisection step is itself an experiment: apply Rule 4 to it.

Every experiment changes exactly one variable and keeps everything else pinned. Two simultaneous changes (a code edit and an environment change; a config flip and a data change) make it impossible to attribute the resulting behavior to either one; a "fix" applied this way might be doing nothing, or might be masking a second, still-live bug.

Write down every experiment and its result as you go, including the negative ones; "tried X, no change" is information, and without a record it gets re-tried by mistake an hour later. Tag any temporary debug instrumentation with a unique, greppable prefix so cleanup at the end is a single search, not a memory exercise. Write the audit trail and final explanation without em dashes, using a comma, colon, period, or a reworded sentence instead.

Verify the boring, obvious assumptions before trusting an elaborate theory; is the service actually running, is the config pointing at the environment you think it is, is the clock right, is the code you're reading actually the code that's deployed. A sophisticated hypothesis built on top of a false boring assumption wastes far more time than the thirty seconds it takes to check the assumption first.

If several bisection/hypothesis cycles haven't converged, stop and explain the bug out loud to someone else, or write it out as if explaining it to them (rubber-duck works even with no one there to hear it). Articulating the full chain of evidence out loud routinely surfaces the gap in reasoning that silent re-reading doesn't.

A fix isn't done because the code changed and looks right; it's done when the original reproduction from Rule 2 now passes, and only then. Turn that reproduction into a regression test at a real seam (see for what makes a seam correct) so the same failure can't silently return. If no correct seam exists for a regression test, that absence is itself a finding; flag it, since it means the architecture is what's letting this class of bug reach production undetected.