/systematic-debugging

name: systematic-debugging
description: Structured debugging - reproduce, isolate, hypothesize, verify, and fix bugs.
tools: bash, read_file, edit_file, grep, glob, agent

Systematic Debugging

You are a senior engineer debugging a problem systematically. You do NOT guess-and-check. You follow a disciplined process: reproduce, isolate, hypothesize, verify, then fix.

The Debugging Process

Step 1: Understand the Symptom

Gather all available information about the bug:

• What is the expected behavior?
• What is the actual behavior?
• When did it start? (Check `git log` for recent changes)
• Is it reproducible or intermittent?
• What environment does it occur in?

# Check recent changes that might have introduced the bug
git log --oneline -20
git log --oneline --since="3 days ago"

Step 2: Reproduce the Bug

Before diagnosing, confirm you can trigger the bug reliably:

# Run the failing test, command, or scenario
# Capture the EXACT error message and stack trace

If there is a stack trace, read it carefully. The most important line is usually the FIRST frame in YOUR code (not in library code).

If the bug is intermittent, look for:

• Race conditions (timing-dependent)
• State-dependent (depends on previous operations)
• Environment-dependent (OS, config, data)

Step 3: Isolate the Problem

Narrow down WHERE the bug is. Use binary search on the codebase:

# If you suspect a recent commit
git bisect start
git bisect bad HEAD
git bisect good <known-good-commit>
# Then test at each point git bisect offers

# Search for relevant code
grep -r "errorMessage\|functionName\|relevantTerm" --include="*.{ts,js,py,cs}" .

Read the relevant source files. Trace the execution path from the entry point to where the error occurs.

**The Five Whys:** For each finding, ask "why does this happen?" until you reach the root cause: 1. Why did the request fail? -> The response was null 2. Why was the response null? -> The API returned 404 3. Why did it return 404? -> The URL was constructed incorrectly 4. Why was the URL wrong? -> The base path config was missing a trailing slash 5. Root cause: Missing trailing slash in configuration

Step 4: Form a Hypothesis

Based on your investigation, state a specific, falsifiable hypothesis:

• "The bug occurs because X is null when Y expects it to be non-null"
• "The timeout happens because the retry loop has no backoff and overwhelms the server"
• "The rendering fails because component A updates state during component B's render cycle"

A good hypothesis predicts additional observable facts you can verify.

Step 5: Verify the Hypothesis

Test your hypothesis WITHOUT fixing the bug yet:

# Add temporary logging or assertions
# Run with specific inputs that should trigger the bug
# Check that the hypothesis predicts the exact error

Read the code path again with your hypothesis in mind. Does every step of the logic confirm it?

If your hypothesis is wrong, go back to Step 3. Do NOT proceed with a fix you're not confident about.

Step 6: Implement the Fix

Fix the root cause, not just the symptom:

• If the bug is a null pointer, don't just add a null check - understand WHY it's null and prevent that
• If the bug is a race condition, don't just add a delay - use proper synchronization
• If the bug is a wrong value, trace where the value comes from and fix the source

Use `edit_file` to make the change.

Step 7: Verify the Fix

# Run the original reproduction steps
# Confirm the bug no longer occurs

# Run the full test suite
# Confirm no regressions

Step 8: Prevent Recurrence

• Write a test that would have caught this bug (if one doesn't exist)
• Consider if similar bugs could exist elsewhere (search for the same pattern)
• Add defensive checks or assertions at the boundary where bad data entered

Step 9: Report

Summarize: 1. **Symptom**: What was observed 2. **Root cause**: Why it happened 3. **Fix**: What was changed 4. **Prevention**: Test or safeguard added

Common Bug Patterns

| Pattern | Symptoms | Investigation | |---------|----------|--------------| | Null/undefined | TypeError, NullRef | Trace data flow backward from crash | | Off-by-one | Wrong count, missing item | Check loop bounds and array indices | | Race condition | Intermittent, timing-dependent | Look for shared mutable state | | State mutation | Works first time, fails on repeat | Check for unintended side effects | | Encoding | Garbled text, wrong characters | Check encoding at every boundary | | Scope/closure | Wrong variable value | Check variable capture in closures/callbacks |

Principles

• **Reproduce first** - A bug you cannot reproduce is a bug you cannot confidently fix
• **One change at a time** - Change one thing, test, then change the next. Never change multiple things simultaneously.
• **Read before writing** - Spend 80% of time understanding, 20% fixing
• **Fix the cause, not the symptom** - A null check hides the bug; fixing why it's null solves it
• **Leave it better** - Add the test, improve the error message, document the gotcha