Debugging

Systematic debugging using hypothesis testing and root cause analysis.

When to Use

• Error investigation (exceptions, crashes)
• Unexpected behavior diagnosis
• Performance issue root cause
• Integration/dependency failures

MCP Workflow

# 1. Get code at error location
serena.find_symbol(name_path="ErrorClass/method", include_body=True)

# 2. Trace call chain
serena.find_referencing_symbols(name_path="ErrorClass/method")

# 3. Search for similar patterns
serena.search_for_pattern("null.*check|error.*handling", relative_path="src/")

# 4. Check past similar issues
claude-mem.search(query="<error-type>", project="<project>")

# 5. Framework error handling
context7.get-library-docs("<framework>", topic="exception handling")

Workflow

1. Observe

- Error message and stack trace
- Steps to reproduce
- When did it start? (recent changes?)
- Scope (one user? all?)

2. Hypothesize

Based on: [observation]
Hypothesis: [proposed cause]
Test: [how to verify]

3. Test

serena.find_symbol("SuspectedClass/method", include_body=True)
serena.find_referencing_symbols("SuspectedCause")
# Log analysis, local reproduction

4. Fix

1. Write failing test that reproduces bug
2. Implement minimal fix
3. Verify test passes
4. Run full test suite

5. Prevent

- Add edge case tests
- Improve validation
- Update documentation

Common Patterns

Null/Undefined

Symptoms: NullPointerException, "undefined is not a function" Investigate:

• Find where null originates
• Trace back through call chain
• Check data presence assumptions

Race Condition

Symptoms: Intermittent, works in debug mode Red flags:

• Shared mutable state
• Missing synchronization
• Execution order assumptions

Data Inconsistency

Investigate:

• Trace data flow source to error
• Check transformation logic
• Verify cache invalidation

Investigation Techniques

Git Bisect

git bisect start
git bisect bad
git bisect good <commit>
# Test middle commit, mark good/bad
git bisect reset

Stack Trace Analysis

Start at bottom (entry point)
Move up to error line
Examine code at that line
Check what could be null/invalid

Divide and Conquer

A -> B -> C -> D (output wrong)
Check B: correct? -> problem in C or D
        wrong?   -> problem in A or B

Output Format

## Bug: [Title]

### Symptoms
- Error: [message]
- Location: `file:line`

### Investigation
**Hypothesis 1:** [description]
- Test: [method]
- Result: Confirmed / Ruled Out

### Root Cause
[Identified cause] at `file:line`

### Fix
[Description]

### Prevention
- [ ] Test added
- [ ] Similar patterns checked

Checklist

• Can reproduce consistently
• Stack trace analyzed
• Root cause identified (not just symptom)
• Failing test written
• Fix implemented
• Full test suite passes