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:

# 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:

# 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:

// 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:

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