systematic-debugging

Systematic Debugging

When to Use

• A bug, error, exception, or crash needs investigation
• Something is "not working" and the cause is unclear
• A test is failing and the reason isn't obvious
• Unexpected behavior needs troubleshooting in any language or framework

Core Workflow

Follow these five phases sequentially. Do not skip ahead to fixing before completing isolation and tracing.

Phase 1: Reproduce

Establish a reliable way to trigger the bug before doing anything else.

1. Read the full error message, stack trace, and logs — note exact text, line numbers, and error codes
2. Create a minimal reproduction case that triggers the issue consistently
3. Record the exact steps, inputs, and environment that cause the failure

Checkpoint: Can you trigger the bug on demand? If intermittent, gather more data before proceeding.

Phase 2: Isolate

Narrow down where the failure originates.

1. Use binary search to find the failing component — disable or stub out halves of the system
2. Check recent changes with git log --oneline -20 and git diff against the last known good state
3. Add targeted logging or use a debugger to observe state at key boundaries

# Find which commit introduced the bug
git bisect start
git bisect bad HEAD
git bisect good <last-known-good-commit>
# Git will checkout midpoints — test each one and mark good/bad

Checkpoint: The bug is traced to a specific function, module, or data flow.

Phase 3: Trace to Root Cause

Understand why the failure happens — not just where.

1. Read the code path completely from entry point through the failure site
2. Check assumptions: what does each function expect vs. what it actually receives?
3. Trace data flow backward — where does the bad value originate?
4. Verify with evidence: add assertions or print statements to confirm your hypothesis

# Example: verify assumptions about incoming data
def process_order(order):
    assert order.status == "pending", f"Expected pending, got {order.status}"
    assert order.items, "Order has no items"
    # ... rest of processing