When you are stuck or lost

This page covers two spots where it is the workflow, not the code, that has stopped moving.

The first is when the AI repeats the same mistake twice and the verification step refuses to pass. The second is when you come back after a few days, or after /clear wiped the chat window, and you cannot remember where you stopped. Neither is a code problem, and the base has two slash commands wired up for these spots.

Slash command	When to call it
/recover-from-blocked	Right after /review-extension writes blocked because two attempts in a row failed
/resume	Whenever “where was I again?” comes up — after /clear, after a few days off, or just because

If 06-troubleshooting.md deals with the environment and the code, this page deals with the layer above that.

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

/review-extension scores the code on six dimensions: permissions, secrets, MV3, FSD, types, and build. A pass writes approved. Something to fix writes changes_requested. Two attempts in a row that fail to land the same spot writes blocked. When you see blocked, that is the system telling you “asking the AI to try again the same way is going to give the same result”.

The command is one line:

/recover-from-blocked

What it looks like when it works — a plain-English readout

When you run the command, the AI does the following automatically.

1. It finds the most recent verification report (.claude/state/review-*.md with the latest timestamp).
2. It pulls the dimensions where the score was low.
3. It compares what the AI changed across the last two attempts (.claude/state/builder-*.md).
4. If the AI touched the same file in the same direction twice, the readout flags that as a repeat.

The output looks like this:

Where things got stuck

The AI was working on the popup UI area, and verification blocked it 2 times.

What did not pass
- permissions (2 / 5): The extension was set up to access every site. We need to narrow it down to the sites it actually needs.
- types (1 / 5): The data shapes in the code do not line up.

What the AI tried
- Attempt 1: changed manifest.json's host_permissions to <all_urls>
- Attempt 2: roughly the same change in a different spot

⚠️ The AI tried fixing the same place the same way both times. Trying again with no extra context is likely to produce the same result.

Current code state
- Last commit: a3f8c12 popup base entry point added (3 hours ago)
- Uncommitted: 4 files modified (working tree dirty)

Some technical terms stay literal (<all_urls> keeps its angle brackets) but a plain explanation always sits next to them, so you can see what to narrow down.

Then it asks you to pick one of three

After the readout, a single question shows up:

How would you like to recover?

A. Roll back to the last point that worked
B. Tell me more, then try again
C. I will fix it myself

What each option does:

A. Roll back to the last point that worked is the recommended option. The AI restores the code to the commit where the last verification was approved. Everything the AI tried since then disappears. You end up back at a clean starting line, and writing more context for the AI before retrying the same area usually works much better the second time.

B. Tell me more, then try again asks you for additional context on the dimension that failed. If permissions blocked it, the question that follows might be “Which sites does this extension actually need to work on?”. You answer in your own words, your answer goes into the AI’s notes as new information, and the AI tries the same area once more. Option B is most useful when the failing dimension is one where you can supply the answer (permissions, what features to drop for bundle size). For type errors or layer-violation problems, option A is usually faster.

C. I will fix it myself prints the file paths involved and exits. You edit them by hand, then run /review-extension again to check.

The safety check on option A

If you pick A, one more confirmation appears before anything is reset:

About to roll back to:
a3f8c12 popup base entry point added (3 hours ago)

This will erase every file the AI made since then. Continue? (yes / no)

git reset --hard only runs if you type yes exactly. Anything else, or just closing the prompt, leaves the working tree alone. That extra step is there on purpose.

If your working tree has unsaved changes, the prompt warns you that those will disappear too. Stop here and copy any file you wanted to keep into a folder outside the project before continuing.

/resume — when you cannot remember where you left off

Run this when /clear wiped the chat window, you came back after a few days, or “where was I?” pops up on its own.

/resume

How it differs from the session-start hook

07-automated-safety-net.md covered session-start.sh, the hook that automatically loads active.md, progress.md, and the rest into the AI’s context at the start of every session. That hook hands the raw contents to the AI.

/resume synthesizes that raw context into a one-screen summary for you.

Mechanism	When	What you actually see
session-start.sh hook	Auto, every new session	The state files load into the AI’s context. The AI knows; you do not see it
/resume command	When you run it	A one-screen summary: “current stage, last work, next recommended command”

The hook is for the AI. /resume is for you. The two work as a pair.

What it looks like — a one-screen summary

The output looks like this:

Current state

Stage: customized (building entry-point screens like popup and options)
Last work (2 days ago): added a backend-mode toggle to the popup UI
Feature progress: 3 / 7 passing
Pace: novice
UI mode: sidepanel
MCP: figma, supabase

Your note for next time (active.md)
"deciding sidepanel colors. next: options page form"

Next natural step
To continue the sidepanel UI, would you like to run /implement-sidepanel-ui?

The summary is meant to fit in around 20 lines. The next step has to be visible at a glance. If progress.md is long, only the last line or two get summarized.

When active.md and the stage do not agree

Sometimes the note you wrote in active.md and the actual stage of the project disagree. For example, active.md says “deciding popup colors” but the project folder does not have a popup yet.

When this happens, /resume shows you the mismatch and asks which one is right. Your active.md note is your spot, so it usually wins, but sometimes there has been work on a different machine, or you finished something and forgot to update the note. The extra check is worth it.

How they fit together in one cycle

The two commands typically come up in this kind of cycle:

1. Working, verification fails twice in a row
   → /recover-from-blocked → option A to roll back
   → write one line in active.md saying what got stuck and the angle to try next

2. Close for the day, come back later
   → /resume → "where I stopped yesterday and what to do next" in one screen

3. Run the suggested slash command for that area again
   → this time you have the extra context written down up front, and it passes

You do not have to memorize both commands separately. Stuck → first command. Lost → second command. Two spots in your head, that is enough.

When the commands do not respond

Both commands trigger skills inside the base’s .claude/skills/ folder. If Claude Code does not recognize the command, it is almost always one of these:

• The fork did not include the .claude/ folder. A normal git clone keeps it, but if someone published a fork that put .claude/ in .gitignore, the folder is missing in your copy. Run ls .claude/skills/ and confirm both recover-from-blocked and resume directories are there.
• The command was typed differently. The exact spellings are /recover-from-blocked and /resume. Spaces or capitalization breaks recognition.

Next

With the workflow safety net in place, you are ready for distribution. The three paths for getting your extension to run on someone else’s machine are written up in 09-distribution.md.