---
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