Structured Debugging

Work through bugs systematically: reproduce, isolate, diagnose, and fix. Avoid the common trap of guessing at fixes before understanding the root cause.

Workflow

Step 1: Understand the Symptom

Gather all available information:

• What is the error? Read the full error message and stack trace carefully.
• When did it start? Check recent deploys, config changes, dependency updates.
• How often does it happen? Always, intermittently, under specific conditions?
• What is the expected behavior? Make sure we know what "working" looks like.
• What environment? Local, staging, production? OS, runtime version, dependencies?

Parse the stack trace to identify:

• The exact file and line where the error originates.
• The call chain that led to the error.
• Whether the error is in application code, a library, or framework.

Step 2: Reproduce the Issue

Before diagnosing, establish a reliable reproduction:

• Try to reproduce locally using the same inputs, environment, and configuration.
• If the user provides steps, follow them exactly.
• If there are no steps, work backward from the error to construct a minimal reproduction.
• Check logs around the time of the error for additional context.

Useful commands:

# Check recent git changes
git log --oneline -20
git diff HEAD~5 -- <relevant files>

# Check application logs
tail -n 100 <log file>

# Check environment
node --version / python --version / etc.
env | grep -i <relevant vars>

If the issue is environment-specific:

• Compare environment variables between working and broken environments.
• Check for differences in dependency versions (lock files).
• Look for configuration differences (feature flags, database endpoints).

Step 3: Isolate the Cause

Narrow down the source systematically:

Binary search through changes:

• If the issue started after a deploy, use git bisect or review the diff between the last known good state and current.
• Check each changed file for relevance to the symptom.

Eliminate hypotheses:

• Form a hypothesis about the cause.
• Design a test that would prove or disprove it.
• Run the test.
• If disproved, move to the next hypothesis. Do not guess-and-check fixes.

Common isolation techniques:

• Comment out or disable suspected code to confirm the source.
• Add targeted logging around the suspected area.
• Test with simplified inputs to rule out data-dependent issues.
• Check if the issue exists on a clean branch (rules out local changes).

Step 4: Diagnose the Root Cause

Once isolated, understand WHY the bug exists:

• Is it a logic error? Trace the actual values through the code path.
• Is it a timing issue? Look for race conditions, missing awaits, stale caches.
• Is it a data issue? Check for unexpected null values, encoding problems, schema mismatches.
• Is it an environment issue? Missing env vars, wrong versions, network connectivity.
• Is it a dependency issue? Breaking change in an update, incompatible versions.

Read the relevant source code carefully. Understand the intended behavior, not just the failing behavior.

Step 5: Implement and Verify the Fix

• Write the fix, targeting the root cause, not the symptom.
• Verify the fix resolves the original reproduction.
• Check for related code that might have the same bug.
• Add or update tests to prevent regression.
• Consider if the fix could have unintended side effects.

Step 6: Document Findings

Briefly summarize what went wrong and why, so the team can learn from it.

Output Format

## Debugging Report

### Symptom
<What was observed — the error, unexpected behavior, or failure>

### Root Cause
<What actually caused the issue and why>

### Investigation Path
1. <First hypothesis tested and result>
2. <Second hypothesis tested and result>
3. <How root cause was confirmed>

### Fix
<What was changed and why this addresses the root cause>

```<language>
// the fix, with a brief explanation

Verification

• <How the fix was verified>
• <What tests were added or updated>

Prevention

• <How to prevent similar issues: better tests, linting rules, monitoring>

## Examples

**User**: Posts a stack trace showing `TypeError: Cannot read properties of undefined`
**Action**: Parse the stack trace to find the exact line. Read that code and its callers. Identify which variable is undefined and trace back to where it should have been set. Check for missing null checks, incorrect destructuring, or async timing issues.

**User**: "This API endpoint returns 500 in prod but works locally"
**Action**: Compare environment configs. Check for missing env vars, database connectivity, or dependency differences. Look at prod logs for the actual error. Investigate differences in data between environments.

**User**: "Tests pass locally but fail in CI"
**Action**: Check CI environment (OS, runtime version, timezone). Look for test ordering dependencies, file system assumptions, or timing-sensitive assertions. Compare CI logs with local output.

## Best Practices

- Read the FULL error message and stack trace before doing anything else. The answer is often right there.
- Do not guess at fixes. Understand the root cause first. A wrong fix can mask the real problem and create harder bugs later.
- One change at a time. If you change three things and it works, you don't know which one fixed it.
- Check the recent git history. Most bugs are caused by recent changes.
- Rubber duck the problem. Explaining the issue step-by-step often reveals the answer.
- When stuck, take a step back and question your assumptions. The bug might not be where you think it is.
- Intermittent bugs are almost always timing, caching, or data-dependent. Look for race conditions and stale state.
- If a fix seems too simple for the symptom, verify extra carefully. You may be fixing a symptom, not the cause.