Systematic Debugging

Debugging: reproduce, isolate, diagnose, fix, verify. Replaces ad-hoc "try random things" with systematic root cause analysis.

When to Use

• Investigating bugs or unexpected behavior
• Test failures with unclear causes
• Runtime errors (crashes, exceptions, wrong output)
• Performance issues (slow, memory leaks)
• User reports "it doesn't work"

Don't use for:

• Writing new code (use technology-specific skills)
• Code review (use critical-partner)
• Planning (use brainstorming)

---

Critical Patterns

✅ REQUIRED: Reproduce First

Never guess at causes. Reproduce the bug reliably before investigating.

## Bug Reproduction

**Reported behavior:** [What user sees]
**Expected behavior:** [What should happen]
**Steps to reproduce:**
1. [Step 1]
2. [Step 2]
3. [Step 3 — bug occurs]

**Reproducible?** Yes/No/Intermittent
**Environment:** [OS, browser, Node version, etc.]

If bug is intermittent: look for race conditions, timing issues, or state-dependent behavior.

✅ REQUIRED: Read the Error Message Completely

// ❌ WRONG: "I got an error" (ignoring the message)
// TypeError: Cannot read properties of undefined (reading 'map')
// → This tells you EXACTLY what's wrong: something is undefined

// ✅ CORRECT: Parse the error message
// 1. Error type: TypeError (type-related, not logic)
// 2. What: Cannot read properties of undefined
// 3. Specifically: reading 'map'
// 4. Therefore: the variable before .map() is undefined
// 5. Question: WHY is it undefined? (check data flow)

✅ REQUIRED: Isolate the Problem

Narrow down where the bug lives using binary search.

## Isolation Strategy

1. **Which layer?** UI / API / Database / External service
2. **Which file?** Add console.log at entry/exit points
3. **Which function?** Step through with debugger
4. **Which line?** Narrow to exact statement
5. **Which value?** Log inputs and outputs

**Binary search**: If 10 possible causes, test the middle one first.
If it passes → bug is in the second half. If it fails → first half.
Repeat until isolated.

✅ REQUIRED: Check Assumptions ("Excuse vs Reality")

Common debugging traps — what developers assume vs what's actually true.

| Developer Says | Reality Check | |---------------|---------------| | "The data is correct" | Log the actual data. Is it what you expect? | | "This function is being called" | Add a log. Is it really being called? With correct args? | | "The API returns the right data" | Check the actual response. Status code? Body? Headers? | | "Nothing changed" | Check git diff. Something always changed | | "It works on my machine" | Check environment differences (versions, config, data) | | "The type is correct" | Log typeof and actual value. TypeScript types are compile-time only | | "The state is updated" | State updates are async in React. Log in useEffect, not after setState |

✅ REQUIRED: Fix and Verify

After finding root cause, fix it and verify the fix works.

## Fix Verification

**Root cause:** [One sentence explaining why the bug occurred]
**Fix:** [What was changed and why]
**Verification:**
- [ ] Original reproduction steps no longer trigger the bug
- [ ] Related functionality still works (regression check)
- [ ] Test added to prevent recurrence
- [ ] Edge cases considered

❌ NEVER: Apply Random Fixes

// ❌ WRONG: "Let me try adding a null check everywhere"
if (data) { if (data.items) { if (data.items.length) { /* ... */ } } }

// ✅ CORRECT: Understand WHY data is undefined
// Question: Where should data come from?
// Answer: API call in useEffect
// Investigation: Is the API call failing? Is state not updating?
// Root cause: API call has wrong endpoint
// Fix: Correct the endpoint (don't add defensive null checks)

---

Decision Tree

Error message present?
  → Read it completely. Parse type, what, and where.
  → See references/common-mistakes.md for common error patterns

No error, wrong behavior?
  → Compare expected vs actual output
  → Log intermediate values to find where divergence starts

Intermittent bug?
  → Race condition? (async operations, event ordering)
  → State-dependent? (different starting conditions)
  → Environment-dependent? (OS, browser, data)

Performance issue?
  → Profile first (don't guess)
  → Measure before and after any change

After finding root cause?
  → Fix the root cause, not the symptom
  → Add test to prevent recurrence
  → Document for team knowledge

---

Example

Debugging "user can't log in" using the systematic approach.

## Bug Reproduction
**Reported behavior:** User enters correct credentials → "Invalid password" error
**Expected behavior:** User is logged in and redirected to dashboard
**Steps to reproduce:**
1. Navigate to /login
2. Enter registered email + correct password → error shown
**Reproducible?** Yes, consistently
**Environment:** Production only; works in dev

## Isolation Strategy
Layer-by-layer:
1. UI layer OK — form submits the right values (verified via Network tab)
2. API layer: POST /auth/login returns 401 → narrows to backend

Add log in AuthService:
  console.log("stored hash:", user.passwordHash);
  console.log("compare result:", await bcrypt.compare(password, user.passwordHash));
  → compare result: false  ← bug confirmed here

## Check Assumptions
"The password hash is correct" → LOG IT
  Actual stored hash: "$2b$12$OLD_ROUNDS..." (bcrypt rounds mismatch)
  Dev DB: rounds=10; Prod DB: rounds=12 — hashes generated with different round counts

## Root Cause
Password hashes in production were generated during a bcrypt config change.
Existing users have hashes with old round count; new bcrypt.compare uses new count.

## Fix Verification
- [ ] Re-hash passwords on next successful login (progressive migration)
- [ ] Verify login works for affected accounts in staging
- [ ] Add test: login with hash from each supported round count
- [ ] Edge case: users who haven't logged in since migration get password reset email

---

Edge Cases

Third-party library bug: Verify with minimal reproduction. Check GitHub issues. Consider workaround vs upgrade vs fork.

Heisenbug (disappears when observed): Logging or debugger changes timing. Use non-intrusive logging or production telemetry.

Works in dev, fails in prod: Check env vars, API endpoints, CORS, minification, tree-shaking.

Flaky tests: Usually timing-dependent. Add proper waits, mock time, or use deterministic test data.

---

Checklist

• [ ] Bug reproduced reliably with clear steps
• [ ] Error message read completely and parsed
• [ ] Problem isolated to specific layer/file/function
• [ ] Assumptions verified (not guessed)
• [ ] Root cause identified (not just symptom)
• [ ] Fix addresses root cause
• [ ] Regression test added
• [ ] Fix verified with original reproduction steps

---

Resources

• debugging-strategies.md — Detailed debugging techniques per technology
• common-mistakes.md — Common error patterns and their causes
• critical-partner — For reviewing fix quality