debugging-workflow

name	debugging-workflow
description	Systematic debugging methodology — reproduce, isolate, bisect, fix, verify. Use when diagnosing failures, tracing errors, or investigating unexpected behavior. TRIGGER when: debug, error, traceback, stack trace, bisect, breakpoint, failing test, unexpected behavior. DO NOT TRIGGER when: writing new features, code review, documentation, refactoring.
allowed-tools	["Read","Grep","Glob","Bash"]

Debugging Workflow

Systematic methodology for diagnosing and fixing bugs. Follow these phases in order — do not skip ahead.

Phase 1: Reproduce

Before anything else, reproduce the failure reliably.

Steps

1. Get the exact error — full traceback, not a summary
2. Find the minimal reproduction — smallest input/command that triggers it
3. Confirm it's consistent — run 3 times. Flaky? Note the frequency
4. Record the environment — Python version, OS, relevant config

Anti-patterns

• FORBIDDEN: Guessing the fix without reproducing first
• FORBIDDEN: Reading code and theorizing without running it
• FORBIDDEN: "I think I know what's wrong" before seeing the error

# Good: run the failing test with verbose output
python -m pytest tests/path/test_file.py::test_name -xvs 2>&1

# Good: reproduce with minimal script
python -c "from module import func; func(failing_input)"

Phase 2: Isolate

Narrow down where the failure originates.

Binary Search (Bisect)

• Code bisect: Comment out half the logic, does it still fail?
• Git bisect: git bisect start, git bisect bad, git bisect good <known-good-commit>
• Input bisect: Halve the input data until you find the minimal failing case

Trace the Call Chain

1. Start at the exception/error location
2. Walk up the call stack — who called this function with what args?
3. Find the first wrong value — where did correct data become incorrect?

# Quick tracing without debugger
import traceback
traceback.print_stack()  # Print call stack at any point

# Targeted print debugging
def suspect_function(data):
    print(f"DEBUG: data type={type(data)}, len={len(data) if hasattr(data, '__len__') else 'N/A'}")
    print(f"DEBUG: data={data!r:.200}")  # First 200 chars of repr

Debugger Usage

# Drop into debugger at specific point
import pdb; pdb.set_trace()      # stdlib
import ipdb; ipdb.set_trace()    # enhanced (if available)
breakpoint()                      # Python 3.7+ (uses PYTHONBREAKPOINT env var)

Debugger commands: n (next), s (step into), c (continue), p expr (print), w (where/stack), u/d (up/down stack)

Phase 3: Diagnose

Identify the root cause, not just the symptom.

Root Cause Categories

Category	Example	Fix Pattern
Wrong type	str where int expected	Add type check or convert
Wrong state	Object not initialized	Fix initialization order
Race condition	File read before write completes	Add synchronization
Missing check	None not handled	Add guard clause
Stale data	Cache not invalidated	Fix cache lifecycle
Wrong assumption	API changed behavior	Update to match reality

The "5 Whys"

Don't stop at the first explanation:

1. Why did the test fail? → KeyError: 'name'
2. Why is 'name' missing? → The dict comes from parse_config()
3. Why doesn't parse_config() include 'name'? → The config file format changed
4. Why did the format change? → A migration script ran but didn't update the schema
5. Why didn't the schema update? → The migration has no test → Root cause

Phase 4: Fix

Apply the minimum change that addresses the root cause.

Rules

• Fix the root cause, not the symptom
• One fix per bug — don't refactor while fixing
• If the fix is > 20 lines, reconsider — you may be fixing the wrong thing
• Add a regression test BEFORE or WITH the fix, never after

Fix Verification Checklist

• The original reproduction now passes
• No existing tests broke
• A new test covers this specific failure
• The fix handles edge cases (None, empty, boundary values)

Phase 5: Verify

Confirm the fix is complete and doesn't introduce new issues.

# Run the specific failing test
python -m pytest tests/path/test_file.py::test_name -xvs

# Run the full test suite
python -m pytest --tb=short

# Run with coverage to verify the fix path is exercised
python -m pytest --cov=module --cov-report=term-missing tests/path/test_file.py

Post-Fix Checks

1. Does the original error still occur? → Must be NO
2. Do all existing tests still pass? → Must be YES
3. Is there a regression test for this bug? → Must be YES
4. Could this bug occur elsewhere? → Search for similar patterns

Common Pitfalls

Pitfall	Why It's Wrong	What To Do Instead
Fix without reproducing	You might fix the wrong thing	Always reproduce first
Fix the symptom	Bug will recur in different form	Find root cause
Large refactor as "fix"	Introduces new bugs	Minimal change only
No regression test	Bug will come back	Test is part of the fix
Skip full test suite	Fix broke something else	Always run full suite