debugging

Debugging

When to use this skill

• Investigating error messages or stack traces
• Diagnosing unexpected behavior
• Fixing failing tests
• Debugging production issues
• Understanding why code doesn't work as expected

Step 1: Reproduce the problem

Before fixing anything, confirm you can reproduce it:

# Run the failing command/test
npm test -- --grep "failing test name"
pytest -xvs test_file.py::test_name

# Check error logs
tail -100 logs/error.log
docker compose logs app --tail 100

Key questions:

• What exactly is the error? (exact message, stack trace)
• When did it start? (recent commit, dependency update?)
• Where does it happen? (specific input, environment, timing?)
• How often? (every time, intermittent, under load?)

Step 2: Read the error carefully

TypeError: Cannot read properties of undefined (reading 'map')
    at UserList (src/components/UserList.tsx:15:23)
    at renderWithHooks (node_modules/react-dom/...)

Parse the stack trace:

1. Error type: TypeError — wrong type, likely null/undefined
2. Message: Cannot read properties of undefined — something is undefined
3. Property: reading 'map' — trying to call .map() on undefined
4. Location: UserList.tsx:15 — exact file and line
5. Context: React component render — data likely not loaded yet

Step 3: Narrow the scope

Binary search approach

If you don't know where the bug is, bisect:

# Git bisect to find the breaking commit
git bisect start
git bisect bad          # Current commit is broken
git bisect good abc123  # This commit was working
# Git will checkout middle commits — test each one
git bisect run npm test

Isolate variables

• Does it fail with minimal input?
• Does it fail in a fresh environment?
• Does it fail without feature flags / config?
• Does it fail with the previous version of dependencies?

Step 4: Inspect state

Check the data

# Search for where the variable is set
grep -rn "userData\s*=" --include="*.ts" src/

# Check database state
psql -c "SELECT * FROM users WHERE id = 123"

# Check API response
curl -s http://localhost:3000/api/users/123 | jq .