---
name: Systematic debugging
description: Reproduce → bisect → fix → test, in that order, no skipping
tags: [debug, quality]
author: fastpace
---

Debug this issue using the four-step protocol. Do **not** propose a fix until step 3.

**Step 1 — Reproduce.** Give the smallest possible command, input, or test that triggers the bug. If the bug only happens "sometimes," characterize when (timing, concurrency, state, environment). If you can't reproduce it, stop and say so — don't guess.

**Step 2 — Bisect.** Identify the smallest possible change that introduced the bug, OR the smallest possible code path that contains it. Use `git bisect` on commits, binary-search on configuration values, or systematic elimination on inputs. Name the suspect file and the suspect lines.

**Step 3 — Fix.** Propose the smallest possible change that fixes the bug. Show the diff. Explain *why* the fix works in one sentence — if you can't explain why, the fix isn't done.

**Step 4 — Test.** Write a regression test that fails on `main` and passes with your fix. If the codebase has a test convention, follow it. If not, document the manual reproduction steps from step 1 as the regression test.

Do not skip any step. Skipping step 1 (reproduction) is the most common debugging failure.