The debugging workflow that actually works

Most developers debug by intuition: try something, check if it works, try something else. This works when you get lucky. When you don't, you're stuck—because you don't have a method.

Debugging is a skill with a learnable process.

Step 1: Reproduce It Reliably

Before you change anything, make sure you can reproduce the bug consistently. If you can't reproduce it, you can't verify you've fixed it.

A bug that happens 'sometimes' is not a reason to start changing code. It's a reason to instrument your code so you can see what's different when it happens.

Step 2: Understand What It Should Do

Before you look at why it's broken, make sure you understand what correct behavior looks like. This sounds obvious. It isn't—many debugging sessions waste time because the developer isn't sure what success looks like.

Step 3: Narrow the Search Space

Binary search applies to debugging. If you're not sure where in the code the problem is, find the midpoint and check whether the bug exists before or after it. Repeat until you've isolated the source.

// Add checkpoint logging to narrow where it breaks:
Log::debug('Before transformation', ['data' => $data]);
$processed = $this->transform($data);
Log::debug('After transformation', ['data' => $processed]);

Step 4: Read the Error Message

Actually read it. The full stack trace. Every line. Developers lose hours because they read the first line of an error and made an assumption about the cause.

Step 5: Change One Thing at a Time

When you have a hypothesis, test it by changing exactly one thing. If you change three things and the bug goes away, you don't know which fix worked. If you change one thing and it goes away, you understand the bug.

Understanding the bug is what prevents writing the same bug again.