agentsclimarketplace

Debug systematically

Skill eveld/claude/skills/debug-systematically

Use when encountering errors or bugs to follow a systematic debugging process instead of jumping to conclusions.From its SKILL.md

Install
npx -y skills add eveld/claude --skill debug-systematically

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 10 stars10 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

4.4 KB, as published. Nobody here has run it

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
    }
}

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:

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"
  • ✅ "That error is telling me exactly what's wrong"

Tools for Debugging

Logging

log.Printf("DEBUG: variable=%+v", variable)

Debugging Tools

# Go
dlv debug ./cmd/app

# Node
node --inspect-brk app.js

# Python
python -m pdb app.py

Test Isolation

# Run single test
go test -v -run TestSpecificFunction
npm test -- --testNamePattern="specific test"
pytest tests/test_file.py::test_function

Example Workflow

Problem: Test failing with "unexpected nil pointer"

Step 1 - Reproduce:

make test
# Output: TestLogin: unexpected nil pointer at handler.go:42

Step 2 - Isolate:

go test ./pkg/auth -v -run TestLogin
# Isolated to auth package, Login function

Step 3 - Hypothesize:

  • H1: handler.service not initialized
  • H2: user.Session is nil
  • H3: request.Context() returning nil

Step 4 - Test:

// Add logging at handler.go:42
log.Printf("DEBUG: handler=%+v", handler)
// Output shows handler.service is nil

Step 5 - Fix:

// In NewHandler()
return &Handler{
    service: NewAuthService(), // Fix: was missing
}

Step 6 - Prevent:

func TestNewHandler(t *testing.T) {
    h := NewHandler()
    require.NotNil(t, h.service)
}

Benefits

  • Systematic approach prevents wasted effort
  • Confirms root cause before fixing
  • Prevents introducing new bugs
  • Documents debugging process for future reference

Keep looking

Skills are one crate of 610,677. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.