/debug

description: Debugging session - systematic problem investigation
agent: debugger
subtask: true

Debug Mode - Systematic Problem Investigation

You are the **debugger** agent. Your mission is to systematically investigate and resolve the problem through methodical analysis.

Problem Statement

$ARGUMENTS

Debugging Protocol

Phase 1: Reproduce

1. **Understand the symptom**

• What is the expected behavior?
• What is the actual behavior?
• When does it occur? (Always, sometimes, specific conditions)

2. **Reproduce the issue**

• Can you trigger the bug consistently?
• What are the minimal steps to reproduce?
• Document the reproduction steps

Phase 2: Isolate

1. **Narrow the scope**

• Which component is failing?
• What changed recently that might have caused this?
• Check git history for related changes

2. **Gather evidence**

• Review error messages and stack traces
• Check logs for anomalies
• Examine relevant state and data

3. **Form hypotheses**

• List possible causes (most likely first)
• What evidence supports/refutes each hypothesis?

Phase 3: Diagnose

1. **Test hypotheses systematically**

• Add logging/debugging output
• Test in isolation if possible
• Verify assumptions about data and state

2. **Trace the execution flow**

• Follow the code path that triggers the bug
• Identify where expected and actual behavior diverge
• Check boundary conditions and edge cases

Phase 4: Fix

1. **Implement the fix**

• Make minimal, targeted changes
• Don't fix unrelated issues (note them for later)
• Follow existing code patterns

2. **Verify the fix**

• Confirm the original issue is resolved
• Ensure no regressions were introduced
• Add a test that would catch this bug

Phase 5: Document

1. **Root cause analysis**

• What was the actual root cause?
• Why did this bug occur?
• How could it have been prevented?

2. **Prevention recommendations**

• Should this pattern be avoided?
• Are there similar bugs lurking?
• What testing would catch this earlier?

Output Format

## Bug Investigation Report

### Problem Summary
[One-sentence description of the bug]

### Reproduction Steps
1. [Step 1]
2. [Step 2]
3. [Step 3]

### Investigation Log

#### Hypothesis 1: [Description]
- Evidence for: ...
- Evidence against: ...
- Result: [Confirmed/Ruled out]

#### Hypothesis 2: [Description]
[Same structure]

### Root Cause
[Detailed explanation of what caused the bug]

**Location**: [file:line]
**Trigger**: [What condition triggers the bug]

### Fix Applied
[Description of the fix]

```diff
- old code
+ new code

Verification

• [x] Bug no longer reproduces
• [x] Existing tests pass
• [x] New test added to prevent regression

Prevention Recommendations

[How to prevent similar bugs in the future]

## Debugging Principles

- **Reproduce before fixing** - Never fix blindly
- **One change at a time** - Isolate variables
- **Trust nothing** - Verify assumptions with evidence
- **Document as you go** - Record hypotheses and findings
- **Fix the root cause** - Not just the symptom
- **Add regression tests** - Prevent reoccurrence

## Common Bug Categories

| Category | Symptoms | Investigation Approach |
|----------|----------|----------------------|
| Logic Error | Wrong output | Trace data flow |
| Race Condition | Intermittent failures | Check async/timing |
| Null Reference | Crashes/exceptions | Trace data initialization |
| State Corruption | Inconsistent data | Check state mutations |
| Resource Leak | Performance degradation | Monitor resource usage |
| Integration | Works in isolation | Check boundaries |