The Stop-and-Replan Discipline

Why Smart Systems Make the Same Wrong Move Repeatedly

The February 2026 tunnel incident lasted hours longer than it needed to. The agent restarted cloudflared. Then reinstalled it. Then rotated the token. Then deleted and recreated the tunnel. Five attempts, all in the same direction. Each one failing in the same way.

The actual problem: macOS TCC (Transparency, Consent, and Control) had blocked network access after an OS update. Cloudflared was never the problem. Zero of the five attempts could have fixed it.

The 2-attempt rule was not in place. If it had been, the stop-and-replan gate would have triggered after attempt 2: "Cloudflared reinstall failed. Same direction as attempt 1. The assumption that cloudflared is the problem appears to be wrong. Re-examine."

That reexamination would have taken five minutes. The actual recovery took two hours of attempts at the wrong module.

The Gate Structure

The gate is structural, not advisory. The discipline is: attempt 1, attempt 2, then stop — regardless of how confident you are in the hypothesis. Confidence is the enemy of the 2-attempt rule because it makes attempt 3 feel justified when it is not.

The replan phase has three required steps:

1. Re-enter plan mode. State what was tried and what failed. This is not a post-mortem — it is active diagnosis. "I tried mocking the database. The test still failed. I tried a different mock implementation. Same result. The assumption that the test failure is caused by database mocking appears wrong."
2. Identify the assumption that was falsified. What did you believe that is no longer supported by evidence? Two database mock failures disproves "the test is failing because of database behavior." What else could cause a test to fail?
3. Communicate the pivot. "I tried X and Y (same direction), both failed. I'm now pivoting to Z because [new assumption]." This is not optional. Silent thrashing — continuing to try without communicating the direction change — is the pattern that turns 2-hour incidents into 6-hour incidents.

The Real Incidents

The two incidents share a structure: a confident initial hypothesis, multiple attempts in the same direction, each failing in the same way, and the real root cause sitting invisible and uninvestigated.

In both cases, the agent had strong contextual evidence for the initial hypothesis. Cloudflared failing is the obvious cause of tunnel failure. CapCut crashing on launch after a system update is plausibly the app binary. These were not bad hypotheses — they were wrong hypotheses that looked right.

The 2-attempt rule is not designed to catch obviously wrong hypotheses. It is designed to catch confidently wrong ones. Confidence is what causes forward-pushing — the feeling that "one more attempt with a slightly different approach should work." Two failures disconfirm that feeling with evidence.

What "Same Direction" Means

The rule triggers on same-direction attempts — the 2-attempt counter resets when the approach changes fundamentally.

Same direction: Attempt 1: mock the database call. Attempt 2: change the mock implementation. Both are database-mocking approaches. → GATE TRIGGERS.

Different direction: Attempt 1: mock the database call. Fails. Attempt 2: check if the test is using a different database connection than the production code. This is a different assumption (connection routing, not mock behavior). → GATE RESETS.

The distinction matters because the 2-attempt rule is about assumptions, not implementations. If you held the same assumption in both attempts — that the database mock is the fix — and both failed, the assumption is wrong. If the second attempt is based on a different assumption, it is genuinely a new direction.

Communicating the Pivot

The pivot communication format is precise:

"I tried X — [describe the specific attempt]. It failed because [describe the failure mode]. I tried Y — [second attempt, same direction]. Same failure. The assumption that [name the assumption] appears to be wrong. I am now pivoting to Z — [new direction] — because [new assumption]."

This format prevents three failure modes:

Silent thrashing prevention. The user knows what has been tried and can redirect before a third wrong-direction attempt is made.

Documentation for the eliminated-hypotheses log. The pivot communication is the raw material for the log entry: hypothesis, attempts, evidence of failure, verdict.

Commitment to the new direction. Stating the new assumption out loud creates accountability to follow it. "I am now checking the TCC permissions" is harder to abandon than "maybe it's permissions?"

The Relationship to Stop-and-Replan in CLAUDE.md

The stop-and-replan discipline is codified in Knox's CLAUDE.md as a behavioral rule:

"If an approach isn't working after 2 attempts, STOP. Do not keep pushing the same direction. Re-enter plan mode, reassess assumptions, and propose a new approach before continuing. Communicate the pivot: 'I tried X and it failed because Y, so I'm pivoting to Z' — don't silently thrash."

This rule exists in CLAUDE.md because the failure mode it prevents is architectural, not accidental. Smart systems with confident hypotheses will keep attempting in the wrong direction until something external stops them. CLAUDE.md is that external stop.

The rule applies to: broken builds, flaky tests, API failures, architecture mismatches, and any implementation that is fighting you. "Fighting" is the signal — if the implementation is pushing back consistently, it is fighting because the approach is wrong, not because the implementation needs more pressure.

Building the Habit

The 2-attempt rule requires practice to internalize because it conflicts with a deeply embedded debugging intuition: "I understand the problem, I just need to get the implementation right." This intuition is correct for deterministic systems where the assumption is solid. It is wrong for AI systems where confident assumptions are regularly wrong.

The way to build the habit: after every failed first attempt, before attempt 2, write down the assumption being tested. After attempt 2 fails, compare what you assumed to what the evidence shows. If the assumption is disproved, the gate triggers. This makes the rule mechanical — it does not require judgment about whether to stop, only judgment about whether the assumption survived the evidence.

The gate triggers. You stop. You identify the wrong assumption. You communicate the pivot. You proceed in a new direction.

That is the discipline.