systematic-debugging

Systematic Debugging

Find bugs efficiently through hypothesis testing, binary search, and structured elimination rather than trial and error.

When to Use

• A bug report or unexpected behavior is described
• Tests are failing for unknown reasons
• Something "used to work" and now does not
• The user says "it does not work" without a clear cause
• A production issue needs rapid root cause identification

Core Patterns

The Debugging Loop

Follow this process for every bug:

1. REPRODUCE    — Confirm the bug exists and get consistent repro steps
2. HYPOTHESIZE  — Form 2-3 theories about the cause
3. TEST         — Design the smallest experiment to confirm/reject each theory
4. ISOLATE      — Narrow down to the exact line/condition
5. FIX          — Apply the minimal fix
6. VERIFY       — Confirm the fix resolves the issue without regressions

# Step 1: Reproduce reliably
# Write down exact steps, inputs, and expected vs actual output

# Step 2: Form hypotheses
# "The null pointer is because user.address is undefined when user has no profile"
# "The timeout is because the database connection pool is exhausted"

# Step 3: Test one hypothesis at a time
# Add a focused log or assertion, not 20 print statements

Binary Search Debugging

When you know something worked at point A and is broken at point B, bisect to find the breaking change:

# Git bisect for finding the breaking commit
git bisect start
git bisect bad                    # Current commit is broken
git bisect good v2.1.0            # This version worked
# Git checks out a midpoint — test it
# Mark as good/bad, repeat until the breaking commit is found
git bisect good   # or: git bisect bad
# ... repeat ...
git bisect reset  # When done

# Automated bisect with a test script
git bisect start HEAD v2.1.0
git bisect run npm test

Apply the same principle to code:

// Binary search within a function: comment out half the logic
// If bug disappears, the problem is in the commented half
// If bug remains, the problem is in the active half
// Repeat until isolated

async function processOrder(order: Order): Promise<Result> {
  const validated = validateOrder(order);        // Phase 1
  const enriched = await enrichWithPricing(validated); // Phase 2
  const reserved = await reserveInventory(enriched);   // Phase 3
  const result = await chargePayment(reserved);        // Phase 4
  return result;
}

// Does the bug occur after Phase 2?
// Comment out Phase 3 and 4 → test → narrow down