systematic-debugging

Systematic Debugging

Iron Law: "NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST"

When to Use

Use this skill when:

• A test fails and you need to understand why
• An error is thrown and you need to find the cause
• A feature behaves unexpectedly
• Performance degrades and you need to identify bottlenecks
• Data corruption occurs and you need to trace the source
• A bug reappears after "fixing" it

Red Flags (Violation Indicators)

Detect these patterns that indicate skipping root cause investigation:

• Fix without understanding - "I'll just add a null check" (why is it null?)
• Skip to solution - "Let me try wrapping this in setTimeout" (why does timing matter?)
• Restart tools - "Let me restart the dev server" (what state is corrupted?)
• Clear cache - "Let me clear the cache" (what cache entry is stale?)
• Change multiple things - "Let me update these 3 files" (which one fixes it?)
• Shouldn't cause problem - "This change shouldn't affect that" (but it does, why?)
• Assume cause - "Must be a race condition" (what evidence supports this?)

Key Concepts

1. Root Cause vs. Symptom

Symptom: What you observe (test fails, error thrown, wrong output) Root Cause: Why it happens (null value, wrong condition, missing await)

Example:

Symptom: "TypeError: Cannot read property 'name' of undefined"
Root Cause: API returns null when user not found, but code expects object

Bad approach: Add user?.name (fixes symptom, not cause) Good approach: Add validation if (!user) throw new NotFoundError() (fixes cause)

2. Data Flow Tracing

Principle: Follow data from source to error point

Steps:

1. Identify error location (stack trace line number)
2. Identify data involved (variable name, object property)
3. Trace backwards: Where does this data come from?
4. Find divergence: Where does actual differ from expected?

Example:

Error: "Expected 'active' but got 'inactive'"
Location: user.test.ts:42 - expect(user.status).toBe('active')
Data: user.status = 'inactive'
Trace: user.status ← updateUser() ← API response ← database
Divergence: Database has status='inactive' (expected 'active')
Root Cause: Test setup didn't create user with active status