Debug

Debugging is an investigation, not a guessing game. Every step produces evidence that either confirms or eliminates a hypothesis. Do not write a single line of fix code until the root cause is confirmed.

Workflow

Bug report
    │
    ▼
1. REPRODUCE   →  establish ground truth
    │
    ▼
2. REDUCE      →  isolate the minimal case
    │
    ▼
3. OBSERVE     →  collect evidence
    │
    ▼
4. HYPOTHESIZE →  form ranked candidates
    │
    ▼
5. EXPERIMENT  →  eliminate candidates one by one
    │
    ▼
6. ROOT CAUSE  →  confirm with evidence, not intuition
    │
    ▼
7. FIX         →  smallest change that removes the root cause
    │
    ▼
8. VERIFY      →  rerun the original reproduction, confirm clean

Step-by-step

1. Reproduce

Goal: establish a reliable way to trigger the bug before touching any code.

Priority order:

1. If a use case / test case already exists → run it and confirm it fails
2. If no test exists → create a minimal reproduction first, then proceed
3. If the bug is intermittent → reproduce it at least 3 times before continuing

A bug you cannot reproduce reliably is a bug you cannot verify you fixed.

2. Reduce

Goal: strip the reproduction down to the smallest input / fewest steps that still triggers the bug.

Techniques:

• Remove unrelated inputs, routes, or modules one by one
• Isolate a single HTTP request, function call, or UI interaction
• Comment out surrounding code until the bug disappears, then add back the minimum
• Binary-search the commit history (git bisect) if the regression is recent

A reduced case makes the root cause obvious and the fix precise.

3. Observe

Goal: collect raw evidence without interpretation yet.

Collect what is relevant to the bug's layer:

Tool-agnostic collection — use whatever is available in the current environment:

• Playwright MCP, Chrome DevTools MCP, or browser devtools → UI/network evidence
• Server log tailing, curl, httpie → API evidence
• Database client, ORM query logging → data evidence
• console.log / structured logging → runtime state

Do not commit to a hypothesis during this step. Collect first, interpret later.

4. Hypothesize

Goal: form a ranked list of candidate root causes based on the evidence.

Format:

H1 (most likely): [cause] — because [evidence that points here]
H2: [cause] — because [evidence]
H3: [cause] — because [evidence]

Rules:

• Each hypothesis must be falsifiable (you can design an experiment to disprove it)
• Start with the layer closest to the symptom, then work outward
• A hypothesis that cannot be tested is not a hypothesis — it is a guess

5. Experiment

Goal: eliminate hypotheses one by one, starting from H1.

For each hypothesis:

1. Design the smallest possible experiment that would disprove it
2. Run it
3. Record the result — confirmed or eliminated
4. Move to the next hypothesis

Do not move to Fix until all alternatives are eliminated and one hypothesis stands alone.

6. Root Cause

Goal: state the root cause with supporting evidence, not intuition.

Required format before writing any fix:

Root cause: [precise statement]
Evidence: [the specific observation that confirms it]
Layer: [where in the stack the defect lives]

If you cannot fill in all three fields, you have not found the root cause yet — return to Observe or Experiment.

7. Fix

Goal: remove the root cause with the smallest possible change.

Rules:

• Fix only the root cause — do not refactor surrounding code unless it is part of the cause
• If the fix touches > 3 files, question whether you have correctly identified the root cause
• If there was no test covering this case → add one now (the reproduction from Step 1 becomes the regression test)
• Do not change unrelated behavior

8. Verify

Goal: confirm the bug is gone and nothing else broke.

Checklist:

[ ] Original reproduction: now passes (or no longer triggers the bug)
[ ] Regression test (if added): green
[ ] Full test suite: green
[ ] Adjacent behavior: manually spot-checked for side effects
[ ] Evidence collected in Step 3: all anomalies are now explained or resolved

Only after all checks pass: declare the bug fixed.

Anti-patterns

Quick reference

Can I reproduce it?          → No: find reproduction first
Can I reduce it further?     → Yes: keep reducing
Do I have a hypothesis?      → No: observe more
Is my hypothesis falsifiable? → No: rephrase or discard it
Is the root cause confirmed?  → No: experiment more
Is my fix minimal?           → No: trim it
Is the original repro green? → No: you are not done