Systematic Debugging

You are investigating a bug using a structured four-phase process. The goal is to find and fix the root cause, not just suppress the symptom.

When to Activate

• Bug reports or unexpected behavior

• Failing tests that shouldn't be failing

• Production issues or error reports

• "It works on my machine" type problems

• Any situation where the cause isn't immediately obvious

Activation

After activation, print the banner (see _shared/observability.md ):

Systematic Debugging activated Trigger: [describe the symptom in your own words — e.g., "test failure in auth flow" or "unexpected 500 on endpoint"] Produces: root cause analysis, regression test, fix

Phase 1: Reproduce

Narrate: Phase 1/4: Reproducing the problem...

Before anything else, reliably reproduce the problem.

Steps

• Understand the report — What's expected? What's happening instead? When did it start?

• Reproduce locally — Run the exact steps that trigger the bug

• Document the reproduction:

Reproduction

Steps: [exact steps] Expected: [what should happen] Actual: [what happens instead] Frequency: [always / intermittent / specific conditions] Environment: [OS, Node version, browser, etc.]

• If intermittent: Identify conditions that increase frequency (load, timing, specific data)

If You Can't Reproduce

• Check environment differences (versions, config, data)

• Add logging to narrow down when/where it occurs

• Ask the reporter for more details

• Do NOT proceed to fixing without reproduction — you'll likely fix the wrong thing

If reproduction fails after reasonable effort, use error recovery (see _shared/observability.md ). AskUserQuestion with options: "Add more logging and retry / Get more info from reporter / Proceed with best guess (risky)."

Narrate: Phase 1/4: Reproducing the problem... done

Phase 2: Isolate

Narrate: Phase 2/4: Isolating the bug...

Narrow down where the bug lives.

Binary Search Strategy

• Identify the boundaries — Which systems/modules are involved in the failing flow?

• Add assertions at boundaries — Verify inputs and outputs at each layer

• Bisect — Is the problem in the frontend or backend? In the handler or the model? In the query or the transformation?

• Narrow until you find the exact location — The specific function, line, or condition

Isolation Techniques

• Git bisect — If the bug is a regression, find the commit that introduced it: git bisect start , git bisect bad , git bisect good [known-good-commit]

• Minimal reproduction — Strip away unrelated code until you have the smallest case that fails

• Logging — Add targeted logging (not scattershot console.log everywhere)

• Assertion insertion — Add assert statements at key points to catch violations

What to Record

Isolation

Location: [file:line or module] Narrowed from: [original scope] → [isolated location] Method: [how you narrowed it down]

Narrate: Phase 2/4: Isolating the bug... done

Phase 3: Analyze Root Cause

Narrate: Phase 3/4: Analyzing root cause...

Understand why the bug exists, not just where.

Root Cause Categories

• Logic error — Code does the wrong thing (off-by-one, wrong operator, missing case)

• State corruption — Data gets into an invalid state (race condition, missing validation, stale cache)

• Integration mismatch — Two components disagree on interface, format, or protocol

• Environment issue — Config, version, or platform difference

• Missing handling — Edge case, error path, or boundary not covered

Analysis Questions

• Why does this code exist? What was the original intent?

• What changed recently? (Check git log for the area)

• Are there similar patterns elsewhere that work correctly? What's different?

• Is this the only place this bug manifests, or is it a systemic issue?

Log the root cause decision (see _shared/observability.md Decision Log format):

Decision: Root cause is [category] — [specific cause] Reason: [evidence from isolation phase] Alternatives: [other hypotheses that were ruled out]

Defense in Depth

After identifying the root cause, ask:

• Why wasn't this caught by tests?

• Why wasn't this caught by types?

• Why wasn't this caught by code review?

• What other similar bugs might exist?

Root Cause

Cause: [precise description] Category: [logic / state / integration / environment / missing handling] Why it wasn't caught: [gap in testing, types, or review] Related risks: [other places with similar patterns]

Narrate: Phase 3/4: Analyzing root cause... done

Phase 4: Fix

Narrate: Phase 4/4: Applying fix...

Fix the root cause and prevent regression.

Fix Process

• Write a failing test that reproduces the bug (TDD red phase)

• Verify the test fails — It should fail for the same reason as the bug

• Apply the minimal fix — Change as little as possible

• Verify the test passes — The fix resolves the bug

• Run the full test suite — The fix doesn't break anything else

• Check for related issues — Fix similar patterns elsewhere if applicable

Log defense-in-depth decisions:

Decision: [which defense-in-depth measures to add] Reason: [what class of bug this prevents] Alternatives: [other measures considered]

Defense-in-Depth Fixes

Beyond the immediate fix, consider:

• Add type constraints that would prevent this class of bug

• Add validation at the boundary where bad data enters

• Add assertions that would catch this sooner

• Improve error messages so the next person gets a clearer signal

Condition-Based Waiting

If the bug involves timing or async behavior:

• Never use arbitrary delays (sleep 5 , setTimeout(5000) )

• Wait for conditions: poll for the expected state, with a timeout

• Example: Instead of sleep 2 && check_result , use i=0; while ! check_result && [ $i -lt 100 ]; do sleep 0.1; i=$((i+1)); done

Fix Report

Fix

Change: [what was changed and why] Files: [list of modified files] Test: [the regression test that was added] Defense: [additional protective measures added] Related fixes: [similar patterns fixed elsewhere, or "none"]

Narrate: Phase 4/4: Applying fix... done

Completion

Present the full debugging report:

Debugging summary. Root cause: [one-line root cause] Fix: [one-line fix description]

Bug: [one-line description] Reproduction → Isolation → Analysis → Fix [Link to each section above]

Regression test: [test name and how to run it] Tests: All passing Build: Clean

Handoff

After the completion report, print this completion marker exactly:

Debugging complete. Artifacts:

• Regression test: [test file path]
• Files changed: [list]
• Defense-in-depth: [additions, or "none"] Compound learning: [If this revealed a pattern, it should be captured via compound-learnings] Returning to the calling workflow.

Rules

• Never fix a bug you can't reproduce — you're guessing

• Never suppress a symptom without understanding the root cause

• Always add a regression test — bugs that come back are morale killers

• Log your debugging process — it helps others (and future you) with similar bugs

• Don't scatter console.log — add targeted, informative logging

• Remove debugging artifacts (extra logs, temporary assertions) before shipping, unless they improve production observability

• If the bug is in a dependency, document the workaround and file an upstream issue