Debugging Like a Pro: A Checklist That Actually Works

Quickstart

If you have a bug open right now, do this in order. The goal is not “stare at the code harder.” The goal is to convert a vague problem into a tiny, deterministic failure you can explain in one sentence.

Overview

Most debugging pain comes from skipping steps. We jump straight to “fixing” without first proving what’s broken, where it’s broken, and what conditions trigger it. The result: changes that don’t help, new bugs, and a growing fear of touching the code.

Core concepts

Think of debugging as moving from a messy real-world incident to a clean, local, deterministic failure. These concepts are the “map” that keeps you from wandering.

Symptom vs root cause

The debugging loop: hypothesis → experiment → evidence

Reduction and bisection: the two superpowers

Invariants: the “must always be true” checks

Invariants are powerful because they fail near the cause. Instead of logging everything, assert what must be true at key boundaries: after parsing, after validation, before saving, before calling an external service, after receiving a response.

Step-by-step

This is the universal flow. Use it for backend bugs, UI issues, data pipeline failures, flaky tests, and production incidents. You can treat it like a decision tree: if you can’t do the current step, go back until you can.

Step 1 — Freeze the story: “expected vs actual”

Step 2 — Get a reliable reproduction loop

The fastest debugging sessions start with a tight loop: run → fail → observe → change → run again. Your goal is a reproduction you can run locally or in a controlled environment.

Step 3 — Reduce to a minimal failing example

Reduction beats brilliance. Instead of “understanding the whole system,” remove parts until the bug is forced to reveal itself. If you can turn a production issue into a single failing unit test, you’re already 80% done.

Step 4 — Bisect: find where “good” turns into “bad”

Bisection is binary search over uncertainty. It’s unbelievably effective when a bug started “recently” or when you suspect a particular change. For code changes, git bisect is the cleanest shortcut to the root cause commit.

# Find the first bad commit using git bisect.
# Prep: you need a command that exits 0 when "good" and non-zero when "bad".

git bisect start
git bisect bad HEAD
git bisect good v2.3.1

# Example test command (replace with your own):
# - a unit test
# - a curl check
# - a script that reproduces the bug
git bisect run ./scripts/repro_check.sh

# When done:
git bisect reset

Step 5 — Instrument the boundary (purposeful logs + invariants)

Instrumentation should answer specific questions: “What are the inputs?”, “What is the intermediate state?”, “Which branch did we take?”, “What assumptions are violated?” The goal is to identify the earliest moment where the system becomes wrong.

Here’s a tiny example of “debuggable code” style: a reproducible runner that checks invariants and prints a single, structured summary. Even if you don’t use Python, copy the idea: controlled inputs, clear boundaries, and assertions that fail close to the cause.

import json
import logging
from dataclasses import dataclass

logging.basicConfig(level=logging.INFO, format="%(levelname)s %(message)s")

@dataclass(frozen=True)
class Order:
    items: list[dict]
    discount_percent: int

def compute_total(order: Order) -> int:
    # Invariants (fail early, near the boundary)
    assert 0 <= order.discount_percent <= 80, "discount out of allowed range"
    assert all("price" in it and "qty" in it for it in order.items), "item missing price/qty"

    subtotal = sum(int(it["price"]) * int(it["qty"]) for it in order.items)
    total = subtotal - int(subtotal * (order.discount_percent / 100))
    return total

def run_repro(path: str) -> None:
    with open(path, "r", encoding="utf-8") as f:
        raw = json.load(f)

    order = Order(items=raw["items"], discount_percent=int(raw.get("discount_percent", 0)))
    total = compute_total(order)

    logging.info("order_total total=%s items=%s discount=%s",
                 total, len(order.items), order.discount_percent)

if __name__ == "__main__":
    # Put a failing payload in repro.json and run this file.
    # Keep the repro small and committed (if possible) so the bug stays reproducible.
    run_repro("repro.json")

Step 6 — Fix the cause, then lock it in with a regression test

A “real fix” has two parts: (1) change that prevents the root cause, and (2) a test/guardrail that fails if the bug returns. Without the second part, you’ve debugged the same bug’s future reincarnation.

If you want a lightweight “prevention net,” start with CI that runs your tests on each push. This keeps regressions from sneaking in during future refactors.

name: ci
on:
  push:
    branches: ["main"]
  pull_request:

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: "3.12"
      - name: Install
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest -q

Common mistakes

These pitfalls show up in every codebase—backend, frontend, ML pipelines, automation scripts. Each one has a simple fix, and applying just a few will noticeably speed up your debugging.

FAQ

What’s the fastest debugging checklist when I’m under pressure?

Run this: write expected vs actual → get a 3/3 repro → reduce → test one hypothesis → fix + regression test. If you can’t do one step, go back until you can. Speed comes from controlling uncertainty, not from jumping ahead.

How do I debug a bug that “only happens in production”?

First, capture a production-quality reproduction: the exact input, config/feature flags, and a correlation ID. Then reduce differences (versions, env vars, data). Add structured logging around boundaries with IDs and timings. Your goal is to reproduce it in a controlled environment, even if it’s a staging environment with production-like data.

Should I use print debugging or a debugger?

Use both, intentionally. A debugger is best when you can reproduce locally and need to inspect state step-by-step. Print/log debugging is best when you need visibility across async flows, remote systems, or production. Either way, tie observations to a hypothesis and remove temporary noise when done.

What’s a “minimal reproducible example” in real-world code?

It’s the smallest code + input that still fails and still represents the real bug. In practice, that might be a single failing unit test, a script that calls an API with a saved payload, or a small dataset slice that triggers the issue. The key is that it runs quickly and fails reliably.

How do I stop reintroducing the same bug later?

Add a regression test or invariant that fails if the bug returns, and run it in CI. Also write a short explanation in the PR (what was wrong, what changed, what inputs triggered it). That documentation is future-you’s shortcut.

When is it better to bisect than to read code?

If the bug “started recently,” bisection is usually the highest ROI move. git bisect tells you the first bad commit; from there you’re debugging a small diff instead of an entire system. Similarly, bisecting data/config quickly reveals which slice contains the trigger.

Cheatsheet

Scan this when you’re stuck. It’s the “keep moving” version of the full checklist.

Wrap-up

Debugging Like a Pro isn’t about knowing every tool—it’s about running the same reliable flow every time: define → reproduce → reduce → localize → prove → fix → prevent. Once you internalize that loop, bugs stop feeling like chaos and start feeling like puzzles with a method.

If you want to get faster at debugging in day-to-day work, pair this checklist with good engineering hygiene: small PRs, clear tests, consistent logging, and a culture of writing down “what we learned” when incidents happen. The related posts below go deeper on common error patterns and workflows.

Related posts

• Top 25 Python Errors (And the 1-Line Fixes)
• Code Review Comments That Improve Code (Without Being Rude)
• Python in 60 Minutes: From Zero to Useful
• Python Dataclasses: Cleaner Models With Less Boilerplate
• Make Python Faster: 12 Micro-Optimizations That Matter
• Asyncio Explained With 3 Real Projects