When the AI gets stuck

This page covers two places where the workflow itself stalls.

One is when the AI repeats the same mistake twice in a row and validation refuses to pass. The other is when you come back after a few days, or right after /clear wiped the chat window, and the memory of where you left off is gone. Neither is a code problem — both are workflow problems. The base ships two slash commands that unstick those seats.

Slash command	When to call it
/recover-from-blocked	Right after /review-e2e failed to pass twice and wrote blocked
/resume	When “where was I?” lights up in your head. Right after /clear, or coming back after a few days away

If Troubleshooting covers the layer where the environment or the test itself is stuck, this page covers the layer above it.

/recover-from-blocked — when the AI made the same mistake twice

As seen in The automated safety net, /review-e2e scores tests across six dimensions (coverage, flakiness, selector quality, test isolation, run performance, maintainability). On a pass it writes approved; with things to fix, changes_requested; and after failing to land the same seat twice in a row, blocked. Seeing blocked is the signal that “telling the AI to try the same thing again will give the same result.”

One typical seat: the test acts before the screen has fully painted, and its flakiness score drops low on both attempts. The first attempt papers over it with an arbitrary wait (a hard sleep); the second drops another sleep at a similar spot. This is where /recover-from-blocked comes in.

/recover-from-blocked

The healthy shape — plain reporting of where it stuck

When you type the command, the AI finds and reads the most recent validation report, compares which dimension scored low and what it tried across the two previous attempts, and reports it in this shape.

Where things stuck

The AI was building the checkout-flow test and got blocked on validation twice.

What did not pass
- Flakiness (1): after clicking the checkout button it moved to the next step before
  the screen finished painting, so the result wobbles from run to run.
- Selector quality (3): it finds the button by its position in the screen structure (CSS),
  so the smallest screen change makes it impossible to find.

What the AI tried
- Attempt 1: dropped an arbitrary wait (sleep) after the button click to mask it
- Attempt 2: only lengthened the sleep at the same spot. The wobble stayed

⚠️ Both attempts tried to fix the same place in similar ways and failed.
Trying again with no extra information is likely to land the same result.

Current code state
- Last commit: a3f8c12 checkout-flow test initial skeleton (3 hours ago)
- Working tree: 2 modified files (dirty)

Technical terms get unpacked on purpose. Even when something like flakiness or selector shows up, a plain-language phrase sits next to it, so you can see what the problem is.

Pick one of three options

After the report, a single question waits.

How would you like to recover?

A. Roll back to the last seat that worked
B. Give me more detail and try once more
C. I want to fix this by hand

A. Roll back to the last seat that worked: the recommended option. The AI reverts the code to the commit where validation last passed. Every change the AI made since then disappears. You start clean from a known seat, write out a bit more context, and let the AI take the same area again. This path usually unblocks fastest.

B. Give me more detail and try once more: you fill in the part the AI got stuck on. If it stalled finding a screen element, a follow-up like “what text is visible on that checkout button?” comes back. Your answer becomes new input, and the same area gets one more shot. The attempt counter resets to zero here — new information counts as a new attempt.

C. I want to fix this by hand: the AI just tells you which file to open and the command ends. You edit it yourself, then run /review-e2e again.

Safety on option A

Picking A surfaces one more explicit confirmation.

Rolling back to:
a3f8c12 checkout-flow test initial skeleton (3 hours ago)

After rollback, every file the AI created since then disappears. Proceed? (yes / no)

Rollback only runs if you type yes. Anything else, or closing the prompt, does nothing. If unsaved changes are sitting in the working tree, a one-line note follows that they also disappear. If you have something you want to keep, stop at that step and copy the file somewhere safe first.

/resume — when you cannot remember where you left off

This is for when /clear wiped the chat window, when you took a few days off, or when “where was I?” just shows up in your head.

/resume

How is this different from the session-start hook

The automated safety net describes how the session-start.sh hook lays state files into the AI context on every new session. That hook drops raw content in — exactly as it sits in the files. The AI sees it; you do not.

/resume composes that raw content into a single-screen summary for you.

Current status

Stage: implemented (tests are written)
Last action (2 days ago): wrote the first version of the checkout-flow test
Feature progress: 2 / 4 passing
Pace: novice
Target / tool: web (Playwright)

Next action you wrote down (active.md)
"Fix the checkout-flow flakiness and re-run /run-suite"

Natural next step
Shall we re-run /run-suite?

The summary is shaped to land inside 20 lines. The whole picture fits one screen, so the next step is right there.

When active.md and the actual stage disagree

Sometimes what you wrote in active.md does not match the actual stage on disk. For example, active.md says “finish writing the checkout-flow test,” but in reality the test skeleton has not even been laid yet. When /resume sees that mismatch, it surfaces both to you and asks which is correct. active.md is something you wrote, so it usually wins — but a stretch of work on another machine can mix the two, which is why it confirms once more.

If review is in a blocked state, /resume catches that and recommends /recover-from-blocked. The two commands interlock like that.

Re-running just one part

You do not have to rewrite the whole thing. If the one stuck flow is checkout, call only that track’s implement-* skill again. The “Next” line of the report usually names which skill to call, so follow it and only the one stuck seat gets reworked.

When the commands do not run

Both commands trigger skills that live in the base’s .claude/skills/ folder. If Claude Code does not recognize the command, it is almost always one of two things: the .claude/ folder did not come along when you forked (check with ls .claude/skills/), or the slash command was typed differently. The exact strings are /recover-from-blocked and /resume.

Next

With the workflow safety net in hand, head to Troubleshooting for when the environment or the test itself breaks.