Skip to main content

The verify loop — proving you fixed it

Writing the fix code is not the end. The most important part of the /debug workflow is the Verify that comes from here.

"It is fixed" does not count as done​

The harness has a principle: "do not assert success; show evidence." In /debug, this is built in as an iteration loop.

SKILL.md iteration protocol (excerpt)
Phase 1: Investigate → Fix → Verify (deepening)
1. Investigate: investigate the cause → form a hypothesis → output a fix proposal
2. Fix: apply the fix (Write/Edit)
3. Verify: run the confirmation method (tests, behavior-check commands)
   - success → go to Phase 2
   - failure → revise the hypothesis and retry (up to 3 iterations)
4. Regression: run related tests and confirm there is no regression

For this fetchUser, Verify looks like this.

Show evidence
$ yarn test user-service
 ✓ fetchUser returns null when the target is missing (regression)
 ✓ fetchUser returns a User when the target exists
 Test Files  1 passed (1)

This test output is exactly the evidence that "it is fixed." Not the words "I fixed it," but the result of actually running the tests. This is the completion condition the harness demands repeatedly.

Why insist on evidence

A model can write "probably fixed" as "fixed." Making a mechanical fact—test output—the completion condition blocks that probabilistic optimism. We do not accept as done what cannot be verified. This is an attitude that runs through the whole harness, not just /debug.

Iterate up to 3 times​

If the first fix does not work, you re-form the hypothesis and retry. At the start of each iteration, a header appears showing which stage you are at.

Output format during iteration
### Debug Pass 2/3
- State: verifying
- Current hypothesis: the return type is fixed, but a missing null check on the caller side remains
- Previous verification result: failure (a different test failed)

Iteration has a quality gate and an upper limit.

  • Quality gate: the tests pass, and the regression tests pass too
  • Upper limit: up to 3 iterations. If it is still not resolved, report with the remaining issues and the next move, and do not force-claim "it is fixed"

This design of "stopping honestly at the limit" prevents a quagmire. The fine-tuning of iteration is defined by a shared protocol called references/iteration-protocol.md (🔧 author's own), which skills other than /debug also reuse as the same framework.

Once fixed, spread it out (Generalize)​

After verification passes, /debug goes one step further. It is the Generalize phase, where it searches with Grep for whether the same pattern of bug exists elsewhere.

SKILL.md Generalize (excerpt)
After the fix succeeds:
- Check with Grep whether the same pattern of bug exists in other places
- If found, append it to the summary (fix if Critical, report only otherwise)
- Propose concrete recurrence-prevention measures (add tests, lint rules, etc.)

This time, it would cross-search for "places that return array[0] raw." If the same way of writing as fetchUser is also in fetchOrder, the same kind of bug likely lurks there. While fixing one bug, you flush out its companions. The result of this Generalize becomes the entrance to "turning learnings into mechanisms" in Ratchet.

Summary of this chapter

The key points:

  • The completion condition is not the words "I fixed it," but the evidence of test output
  • Iterate Investigate→Fix→Verify up to 3 times, converging with a quality gate (tests + regression pass)
  • After trying up to the limit, stop honestly and do not insist on success
  • Once fixed, cross-search for the same pattern of bug in Generalize

Next, in The Stop hook at the end of a response, we look at the final group of inspections that run the moment the answer is returned.