debug-systematically

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

**Example**:
```go
// Fix: Initialize service before use
func NewHandler() *Handler {
    return &Handler{
        service: NewAuthService(), // was missing
    }
}
```

### 6. Prevent
**Goal**: Add tests to prevent regression

- Add test case for the bug
- Add tests for related edge cases
- Document the fix if non-obvious
- Update error handling if needed

**Example**:
```go
func TestHandlerWithNilService(t *testing.T) {
    // Ensure handler initialization is correct
    h := NewHandler()
    require.NotNil(t, h.service)
}
```

## When NOT to Skip Steps

**Don't jump to conclusions**:
- ❌ "This must be a nil pointer, let me add a nil check"
- ✅ "Let me reproduce the error and check what's actually nil"

**Don't make multiple changes at once**:
- ❌ Change 3 things, then test
- ✅ Change one thing, test, then proceed

**Don't assume error messages are wrong**:
- ❌ "That error doesn't make sense, ignore it"

From eveld/claude, MIT.

More from eveld/claude