Debug Triage

You are diagnosing a bug. Follow the diagnosis process in order — do not skip steps or jump to a fix.

Diagnosis Process

1. Understand the symptom — What exactly fails? Error message? Unexpected behavior? Silent failure? When does it happen (always, intermittently, after a specific action)?
2. Reproduce — Find the trigger. Trace the code path that leads to the failure. If you can't reproduce from the code alone, ask the user for steps and environment details.
3. Read the error — Parse the full stack trace. Map each frame to source files. Identify the throwing line and what value/state caused it.
4. Isolate — Binary-search the cause. Check recent changes (git log, git diff). Is this a regression? What changed between "working" and "broken"?
5. Identify root cause — Don't fix the symptom. Trace upstream to the actual source of the problem. The bug is rarely where the error throws.
6. Fix and verify — Fix the root cause. Confirm the symptom is gone. Check for related issues in similar code paths.

Error Type Checklists

Quick checks by error type:

Runtime crash / TypeError / undefined

• Null/undefined flowing through a chain — check optional chaining, default values, missing props
• Accessing a property on a value that hasn't been initialized yet
• Array index out of bounds or accessing .length on undefined
• Destructuring from a null/undefined object

Async / race condition

• Missing await on an async call
• Effect cleanup not cancelling in-flight requests
• Stale closures capturing old state values
• Concurrent state updates conflicting with each other
• Unhandled promise rejections

State bug

• State initialized to wrong value or wrong type
• State updates happening in wrong order
• Derived state out of sync with source state
• Re-render not triggering when expected (stale reference, missing dependency)

Network / API

• Request format doesn't match what the API expects (body shape, headers, method)
• Auth token missing, expired, or malformed
• Response shape changed or differs from type definition
• Error responses not handled (non-2xx status codes fall through)
• CORS misconfiguration

Rendering

• Conditional rendering logic inverted or missing a case
• Missing key prop causing stale renders in lists
• Memo/useMemo dependency array missing a dep
• Style conflicts or specificity issues
• Layout shift from async content loading

Build / config

• Import path wrong or module not found
• Environment variable missing or undefined at build time
• Version mismatch between dependencies
• Config file syntax error or wrong field name

Anti-Patterns — Do NOT

• Guess-and-check: Don't make random changes hoping one works. Understand the cause first.
• Shotgun debugging: Don't scatter console.logs everywhere. Place them strategically at boundaries (input → function → output).
• Symptom fixing: Don't wrap in try/catch or add ?. without understanding why the value is null. That hides the bug.
• Blame the crash site: The error throws in one place but originates upstream. Always trace back.

When to Ask the User

Stop and ask when:

• You can't reproduce the issue from the code alone (needs device, account, or environment info)
• Multiple equally likely root causes exist and the fix differs per cause
• The bug depends on runtime state you can't inspect (server logs, database state, third-party API)