No fix until the bug reproduces

DebuggingFreshModel-agnosticverified 2026-06-21sha deb44f540621

Born in: the post where it earned its place →

Breaks when: It assumes the defect is reproducible at all, and that you can actually run the code. A genuinely nondeterministic heisenbug, an environment-only failure, or a defect whose trigger depends on state the agent cannot recreate locally (a specific production row, a third-party API, a one-off data snapshot) can stall it at the repro gate. A wrong-reason red artifact (setup typo, missing import, inverted assertion) can pass the gate while proving nothing, and a too-narrow repro can pin the wrong trigger and send the fix at the wrong line. It also breaks when immediate containment must precede diagnosis – active security exposure, data corruption, runaway billing, or irreversible user harm – in which case you pause the contract, apply a documented containment plan, then return to reproduction before root-cause repair. It is a discipline gate, not a guarantee the repro captures the real root cause.

Vendor “fix this bug” prompts let the agent jump straight to a plausible diff, so it patches the symptom it imagined and you find out in production whether it guessed right. This contract inverts the order: the first deliverable is a FAILING artifact – a red test or a script that exits non-zero – that pins the real defect, and writing a fix before that artifact exists is forbidden. The un-clonable part is the refusal branch: if it cannot reproduce reliably, it STOPS and reports what is missing instead of shipping a fix nobody can verify.

You are debugging a reported defect. Your first deliverable is NOT a fix. It is a deterministic reproduction, captured as a FAILING artifact. You are forbidden from proposing, writing, or applying any production code change until that artifact exists and you have watched it fail. A patch offered before a captured repro is a failure of this task, no matter how plausible it looks.

DEFECT REPORT:
{{defect_report}}

HOW TO RUN THE CODE / TESTS:
{{verify_cmd}}

PERMITTED WRITES BEFORE THE STEP 3 GATE PASSES: the only files you may create or edit are repro artifacts - tests, fixtures, repro scripts, and notes whose sole purpose is to demonstrate the bug. Any change to production, runtime, or source behavior is forbidden until Step 5, and a change that would survive a wrong hypothesis IS such a change.

NEVER DO THESE UNTIL THE STEP 3 GATE PASSES, even to "set up" the repro: deleting files or data, resetting or migrating a database, updating snapshots or golden files, changing shared config, clearing queues, force-pushing, or mutating any external or shared service. Save your artifact without rewriting the user's working tree - do not stash, checkout, or reset their files. If reproducing seems to require any destructive or hard-to-reverse action, STOP and ask for approval first.

Work the steps in order. Do not start a later step until the earlier one is genuinely done. Report each step's result before moving on.

STEP 1 - State observed vs expected, in one line each.
- OBSERVED: the exact wrong behavior (wrong value, crash, wrong status, leak, hang, wrong output). Quote the real symptom from the report, not a paraphrase of what you assume is wrong.
- EXPECTED: what correct behavior would have been instead.
- If the report does not let you name a concrete observable, say so and go straight to the STOP branch below. You cannot reproduce a symptom you cannot name.

STEP 2 - Build the smallest deterministic trigger.
- Write down the exact command, input, and starting state that makes the defect appear: the command line to run, the precise input or fixture, the environment or config, the data or DB state it assumes. Someone else must be able to paste it and hit the same failure.
- "Deterministic" means deterministic per the artifact type in Step 3, not a single lucky run. For a value/crash/status/output bug it must fail every time; for a hang it must hit the timeout every time; for an intermittent/leak/perf bug see the typed rules in Step 3 - do not fake determinism, and if you cannot make it deterministic by its own type's rule, move to the STOP branch.
- Strip it to the minimum: remove every step, input, and dependency not required to still see the symptom. Be careful here - stripping load, concurrency, or data volume can change or erase the real failure; if the symptom moves or vanishes as you reduce, you have stripped something load-bearing, so restore it and note it as part of the trigger.

STEP 3 - Capture it failing. This is the gate.
- Turn the trigger into a durable artifact: a test that FAILS asserting the EXPECTED behavior from Step 1, or a standalone repro script that exits NON-ZERO on the bug. Prefer the test.
- The artifact must exercise the same public entrypoint, API, command, component, or user path named in the defect report - state the file, function, route, or command it covers. If you must drop to a lower level, justify in one line why that level is equivalent. A tiny test that asserts a value in isolation, never touching the reported path, does NOT count.
- Run the narrow artifact command first, then run {{verify_cmd}} if it is available and relevant. If {{verify_cmd}} cannot execute the artifact, state the exact artifact command you ran and why the provided verifier does not apply. Paste the actual failing output in a fenced block - the assertion that failed or the non-zero exit, with real text. "It fails as expected" with no output shown does NOT pass this gate.
- Typed artifacts by symptom: a HANG is captured as a timeout (non-zero exit, e.g. exit 124) plus a liveness check showing it never completes - never an infinite wait; a LEAK or PERF regression is a before/after measurement compared against a stated threshold, not a vibe; an INTERMITTENT failure must NOT be claimed deterministic - if you cannot make it fail every time, report the X-of-Y failure rate and go to the STOP branch.
- DETERMINISM CHECK: run the artifact 3 times in a row. It must fail all 3 with the SAME failure class. Any pass, or a different failure on one run, means it is not deterministic - report the failure rate and enter the STOP branch.
- SYMPTOM MATCH: quote the one line of output that shows the Step 1 OBSERVED symptom, and state in one sentence why that is the reported defect and not a test bug (a typo, a missing import, the wrong fixture, an inverted assertion that asserts the buggy value as expected). A red artifact that fails for the wrong reason is worse than none - if it does not match, discard it and rewrite the artifact.
- You may not proceed to Step 4 until this artifact exists; state the literal path you saved it at and the exact command to run it, so a reader can re-run it themselves; and it has passed the determinism check and the symptom match.

STEP 4 - HYPOTHESIS AND EXPERIMENT.
- Only now: state ONE hypothesis for the cause - the specific line, branch, or condition you believe produces the observed behavior, and WHY the captured failure points there.
- Name the single experiment that would CONFIRM or DENY it, and run it. The experiment must be READ-ONLY with respect to production code: a log line, an assert, or a print added inside the test or repro script only, or a temporary observation - never a change to production/source behavior. Anything that would survive a wrong hypothesis is a fix, not an experiment, and stays forbidden until Step 5.
- Report what the experiment showed. If it DENIES the hypothesis, discard it and form ONE new hypothesis (repeat this step); you may not advance to a fix on a denied or unconfirmed hypothesis. If after reasonable tries no hypothesis is confirmed, go to the STOP branch and report the denied hypotheses and what you still need.

STEP 5 - FIX (only after a hypothesis is CONFIRMED).
- Write the smallest change that addresses the confirmed cause - no opportunistic refactors, no fixing unrelated things you noticed.
- Re-run the captured artifact from Step 3. It must now PASS for the right reason (the symptom is gone, not the test weakened or deleted). Paste the now-passing output.
- Re-run {{verify_cmd}} if available to confirm you did not break anything else; report the result.

STOP BRANCH - cannot reproduce, or must stop.
- If at any point you cannot produce a deterministic failing artifact - the trigger is flaky, the failure is environment-only, it depends on state you cannot recreate locally, or the report lacks the observable - STOP. Do NOT write, propose, or apply a fix.
- Report: what you tried (commands, inputs, states), what you observed (including partial or intermittent failures with their X-of-Y rate), and exactly what data you still need to reproduce it (a log, a version, a config, a dataset, a reproduction from the reporter).
- A fix shipped without a repro is a guess. Returning "cannot reproduce yet, here is what I need" is the correct, complete answer for this task - not a failure to finish it.

AFTER THE FIX LANDS - regression hunt. RUN THIS SECTION ONLY once Step 5 is done: the captured Step 3 artifact now PASSES for the right reason and {{verify_cmd}} is green. Do not start it earlier; there is nothing to hunt until a fix exists and passes.
- A correct-looking fix can silently break an adjacent contract. The Step 3 artifact only proves the reported symptom is gone, not that everything that leaned on the OLD code path still holds. Hunt those dependents now.
- Enumerate what depended on the code you changed. List, concretely: callers that relied on the old return shape, type, or value range; error or exception paths that the old code took and the new code now skips; defaults, flags, or config values you altered; ordering, timing, or side-effect sequencing the old path guaranteed (writes, events, logs, retries); and any cache, snapshot, or stored value shaped by the old behavior. Name the actual functions, callers, or paths - not a generic category.
- For each item enumerated, run or write the one-line case that would catch a break in it: run an existing test that covers it, or write a quick assertion exercising that caller, that error path, or that default. If a dependent cannot be exercised cheaply, say so and name what manual or follow-up check it needs.
- Report each as caught-green, caught-red, or not-exercised-because. If any case goes red, you have introduced a regression: treat it as a new defect and re-enter this contract at Step 1 for that symptom before claiming done. Do NOT weaken or delete the new case to make it green.
- The captured artifact: its literal path, the exact command to run it, and its real failing output in a fenced block.
- The trigger: the exact command + input + state, minimized.
- One of: (a) the confirmed hypothesis + the experiment that confirmed it + the now-passing output from Step 5, followed by the regression-hunt results (each dependent listed as caught-green, caught-red, or not-exercised-because); (b) the STOP report with the specific missing data; or (c) if every hypothesis was denied and you ran out of moves, say so plainly with the denied hypotheses listed - do not dribble out a vague non-answer.
- One honest line: does a failing artifact that pins THIS defect now exist? You may say yes only with the pasted failing output above. If no, you are in the STOP branch and have not written a fix.

Fill in: defect_report verify_cmd

Shared as is, for reference. Read it and decide what it will do before you run it; using it is your responsibility, under the terms.