stuck-detection

name	stuck-detection
description	Use the moment the same error, test failure, or rejection happens TWICE in a row, when you notice retry-with-minor-variation behavior, when elapsed effort is 2x your prediction, or when you're about to try the same approach "one more time but harder". Encodes the stop/strategy-switch/escalate ladder. Trigger proactively — by the third identical failure you are burning context and user trust.

Stuck Detection

Loops feel like persistence from the inside. Use an external rule, not vibes.

The ladder

Strike 1 — a failure. Fine. Read the error fully (not the first line), form a hypothesis, fix the hypothesized cause, not the symptom.

Strike 2 — same failure class — STOP. You now have evidence your model of the system is wrong. Out loud, in one or two sentences:

1. What I believed: ___
2. What reality said: ___
3. Therefore the broken assumption is probably: ___ Then SWITCH STRATEGY CLASS, don't re-parameterize the same one:

• guessing → instrumenting (logs, minimal repro, bisect)
• editing → reading (the actual docs/source, not your memory of them)
• bottom-up patching → top-down re-design of the small piece
• doing → searching (someone has hit this exact wall)

Strike 3 — still the same class — ESCALATE. Tell the user: what you tried, the two hypotheses you've falsified, the one you can't test without input/access, and a recommended next step. Asking at strike 3 is competence; asking at strike 7 after silent flailing is the failure.

Same root cause, different site (the workaround trap)

The ladder above keys on a repeated identical failure. This variant fires on a repeated workaround of one defect across N call sites. When you reach for the SECOND per-consumer patch of the same underlying flaw in a SHARED primitive (design-system component, util, base class, schema), that IS strike 2 — STOP. Fix it at the source instead of parking another local patch. Per-consumer workarounds compound: every current and future consumer re-pays the same cost, and the real defect is now hidden behind N divergent band-aids.

Tell: "I'll just add a conditional/override/guard here too, like I did in X." If the cause lives upstream of the call site, the fix belongs upstream. If you cannot fix the source now, escalate the source defect — don't silently mint a third patch.

provenance: 2026-06-16 cross-Grove retro; a @swarm/ui closed-overlay full-bleed quirk was worked around 3 separate times (B2 Dialog, W3 Sheet, a site consumer; transcript 6d93d19f) before one source fix (810c8b69). The Phase-6 source fix self-correcting the build is the evidence the rule is right; the two prior recurrences are what it cost.

Worked example — switch the CAUSE class, not the surface

A trunk-lease / HEAD-divergence guard keys on the session's HEAD-vs-trunk, NOT the write target. So changing WHERE you write (repo → Desktop) or HOW (Write tool → shell heredoc) is the SAME strategy class — every variant re-blocks. The real switch is changing the session's relationship to the trunk: re-baseline (HARNESS_TRUNK_LEASE_OK=1, per command) or move to a separate checkout (a worktree-isolated Agent). If two consecutive "fixes" both vary the surface and not the cause, that IS the stuck signal — stop and re-classify (this is the strike-2 "don't re-parameterize the same class" rule applied to guards, not bugs).

Expected trigger — your own merge stales your own lease. A gh pr merge / ff that advances main mid-session leaves your lease at the pre-merge HEAD, so the FIRST mutating op right after blocks ONCE — that is the guard working, not a peer. Re-baseline and proceed; don't go hunting for a phantom concurrent session. (The re-baseline token must LEAD the command — a cd … or space-valued VAR= in front silently no-ops it; see skill windows-host-paths §A for the mechanics.)

Proactive heuristic: re-classify your work-mode on transition. A read-only brainstorm on shared main is fine; the moment work turns write-heavy (prototype, commits, PRs) under a known-active concurrent peer, move to a worktree BEFORE the first block — not after the fifth.

A recurring failure? Search the record before re-fixing

Before drafting ANY fix for a failure you recognize as recurring: (a) restate the core problem in one sentence, (b) pull the cross-session ledger — python3 skills/auto-healer/heal.py match --file <f> --error "..." — and do NOT repeat any hypothesis it lists as already falsified, and (c) find where the recurrence is already documented — grep memory/decisions/ for an ADR on it. If a prior ADR REJECTED a class of fix, the new fix must escape that wall by a DIFFERENT mechanism, not iterate on the rejected one. Skipping this re-proposes a smarter version of a fix that already failed.

provenance: 2026-06-19, session 2b5c4d70 — recurring trunk-HEAD collisions were already documented in ADR 0007, which had rejected actor-identity blocking. Naming that recurrence first led to a resource-state CAS lease (ADR 0009) instead of another smarter warning that would have hit the same wall.

Afterwards, always

Log the prediction miss (harness outcome <id> --result miss --notes ...), and route the lesson: mechanical cause → propose a hook; knowledge gap → skill or reference; misread the user → user-model entry. A derailment you don't route WILL recur, and next time it costs the same.

And when the ladder fired on a real bug, record it in the cross-session ledger so the next session inherits your falsified hypotheses instead of re-deriving them: python3 skills/auto-healer/heal.py bug add …, then one attempt add <bug-id> … --outcome failed per hypothesis you ruled out. This ladder is the IN-session half; the auto-healer skill is the cross-session record (pull it via /heal, never pushed). The boundary is symmetric — see auto-healer's "Boundary vs stuck-detection".