The protocol

Free sample

Four stages: reproduce, locate with citations, fix minimally, confirm it was the cause.

debug/protocol.md · 2.6 KB

debug/protocol.md

# The debugging protocol

The whole protocol in one line: **no diagnosis until there is a reproduction
you watched run.**

## Why this rule and not a better prompt

Given a text description of a bug, a model produces the most likely cause
for that shape of description. Sometimes correct. When it is not, you have
implemented a fix for a bug you do not have — and the symptom persists, so a
second theory arrives, equally confident, with the first fix still in the
codebase.

After four rounds you have a diff full of unrelated defensive code and the
original bug.

## Stage 1 — reproduce

```
There is a bug: [symptom, exact input, exact wrong output].

Do not propose a cause. First:
1. Ask me for anything you need that I have not given you. Do not guess.
2. Write the smallest test that reproduces this failure.
3. Run it. Show me the actual output.
4. If it fails, confirm it fails for the expected reason — quote the
   assertion and the actual value.
5. If it does NOT fail, stop and tell me. Do NOT adjust the test until it
   fails; that reproduces a different bug.

Do not write a fix. Do not modify any non-test file.
```

## Stage 2 — locate, with evidence

```
The reproduction works. Now find the cause.

For each step of your reasoning, quote the line of code or the log output
that supports it. If a step is an inference rather than something you read,
say INFERRED and say what would confirm it.

Do not propose a fix yet.
```

Requiring citations does not make a model honest. It makes unsupported steps
visible to *you*, because a step with nothing quotable under it has nothing
under it. You will see the gap.

## Stage 3 — fix, minimally

```
Fix the cause you identified. Rules:
- Smallest change that makes the failing test pass.
- Do not fix anything else you noticed. List those separately.
- Do not refactor.
- Do not add defensive code for cases we have not seen.
- Run the failing test and the full suite. Show both outputs.
```

## Stage 4 — confirm it was the cause

```
Revert your fix. Confirm the test fails again. Reapply. Confirm it passes.
Show me both runs.
```

Thirty seconds, and it is the only thing that distinguishes "the symptom
went away" from "I fixed the cause".

## When reproduction is genuinely hard

The bar moves, the rule does not. Acceptable evidence:

- A log line from the real failure, quoted exactly
- A stack trace with real line numbers
- A query against a copy of real data, with output
- An instrumented build printing state at the failure

Not acceptable: a theory with nothing under it. If you truly cannot get
evidence, the next step is instrumentation, not a patch.

That was one of 20 files

The rest of Review & Repair is written the same way. $29 once, yours permanently, 14-day refund.

# The debugging protocol The whole protocol in one line: **no diagnosis until there is a reproduction you watched run.** ## Why this rule and not a better prompt Given a text description of a bug, a model produces the most likely cause for that shape of description. Sometimes correct. When it is not, you have implemented a fix for a bug you do not have — and the symptom persists, so a second theory arrives, equally confident, with the first fix still in the codebase. After four rounds you have a diff full of unrelated defensive code and the original bug. ## Stage 1 — reproduce ``` There is a bug: [symptom, exact input, exact wrong output]. Do not propose a cause. First: 1. Ask me for anything you need that I have not given you. Do not guess. 2. Write the smallest test that reproduces this failure. 3. Run it. Show me the actual output. 4. If it fails, confirm it fails for the expected reason — quote the assertion and the actual value. 5. If it does NOT fail, stop and tell me. Do NOT adjust the test until it fails; that reproduces a different bug. Do not write a fix. Do not modify any non-test file. ``` ## Stage 2 — locate, with evidence ``` The reproduction works. Now find the cause. For each step of your reasoning, quote the line of code or the log output that supports it. If a step is an inference rather than something you read, say INFERRED and say what would confirm it. Do not propose a fix yet. ``` Requiring citations does not make a model honest. It makes unsupported steps visible to *you*, because a step with nothing quotable under it has nothing under it. You will see the gap. ## Stage 3 — fix, minimally ``` Fix the cause you identified. Rules: - Smallest change that makes the failing test pass. - Do not fix anything else you noticed. List those separately. - Do not refactor. - Do not add defensive code for cases we have not seen. - Run the failing test and the full suite. Show both outputs. ``` ## Stage 4 — confirm it was the cause ``` Revert your fix. Confirm the test fails again. Reapply. Confirm it passes. Show me both runs. ``` Thirty seconds, and it is the only thing that distinguishes "the symptom went away" from "I fixed the cause". ## When reproduction is genuinely hard The bar moves, the rule does not. Acceptable evidence: - A log line from the real failure, quoted exactly - A stack trace with real line numbers - A query against a copy of real data, with output - An instrumented build printing state at the failure Not acceptable: a theory with nothing under it. If you truly cannot get evidence, the next step is instrumentation, not a patch.