debugging-workflowlisted

# 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 ```bash # 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? ```python # Quick tracing without de