systematic-debugging

name	systematic-debugging
description	Structured approach to finding and fixing bugs
version	1.0.0
author	Ariff
when_to_use	When debugging - follow systematic process instead of guessing

Systematic Debugging

The Process

REPRODUCE → ISOLATE → TRACE → FIX → VERIFY

Never skip steps. Never guess.

Step 1: Reproduce

Goal: See the bug happen reliably

1. Get exact reproduction steps
2. Run them yourself
3. See the exact error
4. Document: input, output, expected

Red flags:

• "It happens sometimes" → Find the condition
• "I can't reproduce" → Get more details from reporter
• Skipping this step → You'll waste time guessing

Step 2: Isolate

Goal: Find minimum case that shows bug

1. Start removing things
2. Does bug still happen?
3. Keep removing until minimal
4. Result: smallest repro case

Why this matters:

• Smaller case = easier to debug
• Reveals what's actually involved
• Eliminates red herrings

Step 3: Trace

Goal: Find root cause (use root-cause-tracing skill)

1. Start at symptom
2. Trace backward: where does bad value come from?
3. Keep asking "where did THIS come from?"
4. Stop when you find origin

Tools:

• Print/log statements
• Debugger breakpoints
• Code reading
• Test isolation

Step 4: Fix

Goal: Change code at root cause

1. Write failing test first
2. Make minimal change to fix
3. Verify test passes
4. Check for side effects

Anti-patterns:

• Big refactor during bugfix
• Fixing symptoms not cause
• No test for the fix

Step 5: Verify

Goal: Confirm fix works and nothing broke

1. Run original reproduction
2. Bug should be gone
3. Run full test suite
4. No regressions

Must have:

• Fresh reproduction attempt
• All tests passing
• No new warnings/errors

Common Bug Types

Type	Debug Strategy
Null/undefined	Trace where value should've been set
Wrong value	Log at each transformation step
Race condition	Add logging with timestamps
State corruption	Find all state modifiers
Off-by-one	Check loop bounds and indices
Missing case	Check all switch/if branches

Debug Log Pattern

When adding debug logs:

// Include: location, variable name, value, timestamp
console.log('[user.ts:45]', 'userId:', userId, Date.now());

Clean up logs before committing.

Bisect Strategy

When you don't know what broke it:

1. Find last known working version
2. Find first broken version
3. Binary search between them
4. Each step: does bug exist?
5. Result: exact commit that broke it

Integration with Skills

• root-cause-tracing → For step 3 (Trace)
• defense-in-depth → For step 5 (Verify)
• verification-before-completion → Before claiming fixed

Integration with Checkers

• assumption-checker → What assumptions about the code?
• fact-checker → Verify claims about behavior
• pre-action-verifier → Before applying fix