Debug

Debug: Triage + Repro

Debugging is a search, not a guess. The fastest path is almost always: reproduce → isolate → understand → fix → prove. Resist the urge to change code before you can reproduce the failure.

1. Triage — understand the report

• Capture the exact symptom: error message, stack trace, wrong output, or the gap between expected and actual. Quote it verbatim; don't paraphrase.
• Establish the blast radius: one user or all? one route or the app? since when? Correlate with the last deploy, migration, or dependency change.
• Note the environment where it fails (local / CI / prod) and where it doesn't. The difference between them is a clue.
• Severity check: if it's a live incident, mitigate first (roll back, feature-flag off) then debug calmly. Don't debug a fire.

2. Reproduce — make it happen on demand

A bug you can't reproduce, you can't fix — you can only guess. Invest here.

• Find the smallest input/steps that trigger it. Strip away everything that isn't required to reproduce.
• Turn the repro into a failing test (pnpm test). This is the single highest-leverage move: it pins the bug, becomes the fix's proof, and prevents regression. Write it before touching the fix.
• For flaky failures: run it in a loop (for i in {1..50}; do ...), fix a seed, remove Date.now()/random/timezone/ordering nondeterminism, and check for shared state between tests.
• For "works locally, fails in CI/prod": diff the environments — Node version, env vars, timezone, DB state, migration level, case-sensitive filesystem, network.

3. Isolate — bisect toward the cause

• Bisect in time: git bisect (or git log on the touched files) to find the commit that introduced it.
• Bisect in space: comment out / short-circuit halves of the pipeline until the failure disappears. The boundary is your suspect.
• Read the stack trace bottom-up to the first line in your code; that's usually where to look, not the library frame at the top.
• Form one hypothesis at a time and test it. "I think X is null here" → add an assertion/log → confirm or kill it. Don't change three things at once.

4. Instrument — see the actual state

• Log the real values at the boundary where expected diverges from actual — inputs, the branch taken, the return value. Print types, not just values (typeof, Array.isArray, null vs undefined).
• Use a debugger/breakpoint for complex control flow; use targeted logging for async, timing, and distributed flows.
• In this stack: check the Network tab for API-route responses, server logs for the actual SQL and its parameters, and whether the failure is client- or server-side (Next.js hydration mismatches masquerade as logic bugs).
• Remove all temporary instrumentation before you finish.

5. Fix the root cause, not the symptom

• Ask "why" until you hit the real cause. A null check that silences a crash is a bandage if the value should never have been null — fix where it became null.
• Prefer the fix that makes the whole class of bug impossible (a type, an invariant, a constraint) over patching this one instance.
• Keep the fix minimal and scoped. Don't refactor while fixing — one concern at a time.

6. Prove it and close out

• The test from step 2 now passes; the full suite still passes (pnpm test). The harness Stop gate will hold you to this.
• Confirm you fixed the reported symptom, not just a plausible-looking nearby thing.
• If the bug could recur elsewhere, grep for the same pattern and note it. If it was a class of mistake, consider whether a lint rule or type prevents the next one.
• State plainly what the cause was and why the fix addresses it — a one-line post-mortem beats a silent commit.

Anti-patterns

• Changing code hoping it helps, without a reproduction or a hypothesis ("shotgun debugging").
• "Fixing" a flaky test by adding sleep or a retry instead of finding the race.
• Swallowing the error (catch {}) to make the red go away.
• Blaming the framework/library first — it's your code until proven otherwise.