Part of Mechanisms of Vibe Coding

Mechanism: Stuck Detection

One-sentence definition

Stuck detection is recognizing when the same failure repeats across N agent passes — same test, same error, same wrong layer — and changing strategy instead of running another identical loop pass.

The problem

Pass 4 and pass 7 show the same assertion failure. The agent rephrases fixes; the root cause is unchanged — wrong file, wrong assumption, or missing context. More iterations without detection burns time and grows messy diffs.

Without stuck detection, loops become infinite hope.

Symptoms:

• Identical error text three or more times
• Agent alternates between two wrong fixes
• Diff churn, test still red
• You paste the same log repeatedly

How it works

Define stuck before looping:

  Same verify failure hash N times (e.g. N=3)
  OR
  Same file edited with same test fail
       │
       ▼
  STUCK — do not repeat prompt
       │
       ▼
  Strategy change (pick one):
    · [Progressive disclosure](/mechanism-progressive-disclosure/) — add missing file
    · [Example-driven spec](/mechanism-example-driven-spec/) — clarify expected behavior
    · [Mode switch](/mechanism-mode-switching/) — debug trace only
    · [Escalation](/mechanism-escalation/) — model, human, smaller slice
    · [Rollback](/mechanism-rollback/) — reset diff, replan

Log: “Stuck at N=3 on health uptime; switched to debug bootstrap order.”

When to use it

• Inside any loop after N identical failures (N=2 or 3 typical)
• Before burning termination max passes on same error
• Team retros on agent sessions that “went nowhere”

When not to use it

• Flaky test — failure not identical; fix flakiness first
• N=1 — normal retry, not stuck
• Changing error each pass — progress, not stuck; adjust verify

Failure modes

Ignore stuck signal — Pass 10 same error. Fix: Hard stop at N; force strategy menu.

Fake strategy change — New model, same prompt and files. Fix: Change input, not just model.

Stuck without rollback — Layered bad edits. Fix: Rollback then new strategy.

N too high — N=10 wastes day. Fix: N=3 for routine work.

Minimal example

Context: details.uptime still 0 after three passes editing health.ts only.

Stuck fired: Same assertion, same file focus.

Strategy change: Debug bootstrap startup order; add @bootstrap.ts (progressive disclosure); no more health.ts-only attempts until trace done.

Done when: Failure signature changed (new info) or test passed — not pass 4 of same edit pattern.

Tool instances (optional deep-dive)

Portable idea above; this section is tool-specific. Date: June 2026.

Cursor

• Rules: “After 3 identical test failures, stop editing and propose strategy change.”
• Track failure substring in handoff block.
• Escalation ladder triggered by stuck rule.

Related mechanisms

• Escalation — what to do when stuck fires
• Loop — stuck detection prevents bad loops
• Progressive disclosure — common strategy change

Try it yourself

Exercise: Set N=3 for your next loop. When hit, write strategy change before pass 4 — mandatory.

Done when: Pass 4 differed from passes 1–3 in approach, not wording.