Spaces:
Running
Running
File size: 2,347 Bytes
81aa0b5 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 | ---
name: debugging
description: Systematic debugging workflow for diagnosing and fixing errors. Use when the user reports a bug, crash, or unexpected behavior.
language: any
tags: debug, errors, troubleshooting, fix
---
# Debugging
Approach debugging systematically. Don't guess — investigate.
## Phase 1: Reproduce
**Goal**: Make the bug happen reliably.
- Ask: what exact steps trigger it?
- Ask: what was the expected vs actual behavior?
- Ask: is it consistent or intermittent?
- If you can reproduce it locally, do so with `bash` and capture the full error output.
## Phase 2: Isolate
**Goal**: Find the smallest scope where the bug reproduces.
- Read the relevant code with `read_file`
- Trace the data flow from input to failure point
- Add temporary print/logging statements if needed
- Identify the exact line where things go wrong
## Phase 3: Diagnose
**Goal**: Understand WHY the bug happens.
Common root causes:
- **Null/None/undefined**: missing null checks
- **Type confusion**: passing wrong type, silent coercion
- **Off-by-one**: loop bounds, slicing
- **Race conditions**: shared state, async ordering
- **Stale state**: cached data not invalidated
- **Wrong assumption**: code expects something the caller doesn't guarantee
- **Environment**: missing env vars, wrong paths, permissions
State the root cause in one sentence before fixing.
## Phase 4: Fix
**Goal**: Apply the minimal correct fix.
- Fix the root cause, not the symptom
- Don't introduce new patterns — match the surrounding code style
- Add a comment if the fix is non-obvious
- Consider: are there other places with the same bug?
## Phase 5: Verify
**Goal**: Confirm the fix works and doesn't break anything.
- Re-run the reproduction steps
- Run any existing tests with `bash`
- Test edge cases related to the bug
- Check that you haven't introduced regressions
## Phase 6: Document
**Goal**: Prevent recurrence.
- If appropriate, add a regression test
- Update relevant docs/comments
- Note the fix in the commit message
## Anti-patterns to avoid
- ❌ Shotgun debugging: changing random things hoping it works
- ❌ Fixing symptoms: papering over the real issue
- ❌ Adding null checks everywhere: hiding the real bug
- ❌ "Works on my machine": dismissing environmental factors
- ❌ Skipping verification: assuming the fix works
|