debug-systematically

# Debug Systematically

Follow a structured debugging process when encountering errors or unexpected behavior.

## Debugging Process

### 1. Reproduce
**Goal**: Confirm the error consistently occurs

- Run the failing command/test again
- Document exact steps to reproduce
- Note any error messages verbatim
- Check if error is consistent or intermittent

**Example**:
```bash
# Reproduce the error
make test

# Document output
Error: undefined method 'foo' on line 42
```

### 2. Isolate
**Goal**: Narrow down to specific component/function

- Identify which component is failing
- Remove unrelated code to isolate issue
- Check if error occurs with minimal input
- Use binary search to find breaking change

**Example**:
```bash
# Test individual components
go test ./pkg/auth/handler_test.go -v -run TestLogin

# Isolate to specific function
go test ./pkg/auth -v -run TestLogin/valid_credentials
```

### 3. Hypothesize
**Goal**: Form testable theories about the cause

- Based on error message, what could cause this?
- What changed recently that might affect this?
- What assumptions might be wrong?
- What edge cases aren't handled?

**Examples**:
- Hypothesis 1: Nil pointer - missing initialization
- Hypothesis 2: Type mismatch - wrong function signature
- Hypothesis 3: Race condition - concurrent access

### 4. Test Hypotheses
**Goal**: Verify each hypothesis systematically

- Test one hypothesis at a time
- Add logging/debugging to verify assumptions
- Check related code for similar patterns
- Look at test failures for clues

**Example**:
```go
// Test hypothesis 1: nil pointer
if handler.service == nil {
    log.Printf("DEBUG: service is nil")
}

// Test hypothesis 2: check types
log.Printf("DEBUG: user type=%T, expected=*User", user)
```

### 5. Fix
**Goal**: Apply fix and verify it resolves the issue

- Implement the fix for confirmed root cause
- Run the originally failing test/command
- Verify fix doesn't break other functionality
- Clean up any debug logging

**Exampl