When you are stuck or lost

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-saas 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 09-troubleshooting.md covers the layer where the environment or the code itself is stuck, this page covers the layer above it.

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

/review-saas scores AI-written code across six dimensions (security, secrets, accessibility, SEO, types, build). 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 AI forgets the signature check on a Stripe webhook and gets blocked twice on review. The first attempt has stripe.webhooks.constructEvent missing from the webhook handler; the second has the same function failing the same check in a different line. The security dimension scores low both times. 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 does the following automatically:

1. Finds and reads the most recent validation report (.claude/state/review-*.md, latest timestamp).
2. Extracts which dimension scored low.
3. Compares what the AI fixed across the two previous attempts (.claude/state/builder-*.md).
4. If the same file got patched in the same direction twice, flags that to you.

The screen prints a report in this shape:

Where things stuck

The AI was building the Stripe webhook seat and got blocked on validation twice.

What did not pass
- Security (2): the webhook function is writing the body straight into the DB without
  verifying the signature. A forged webhook could activate an arbitrary subscription.
- Secrets (3): STRIPE_WEBHOOK_SECRET is sitting in .env.local. Edge Functions cannot
  read that seat. It has to move to supabase secrets set.

What the AI tried
- Attempt 1: handler written without stripe.webhooks.constructEvent
- Attempt 2: the verification seat got wrapped in try/catch, but no actual verification

⚠️ Both attempts patched the same line in similar ways. Trying again with no extra
  information is likely to land the same result.

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

Technical terms get unpacked on purpose. Even when something like constructEvent shows up, a plain-language phrase sits next to it, so you can see what to touch without a translator.

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

What each one does:

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 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 dimension the AI got stuck on. If it stalled on webhook security, the follow-up question is something like “what secret signs this webhook, and where does that secret live right now?” Your answer becomes new input to the AI, and the same area gets one more shot. This option works well when the stuck dimension is one a non-developer can actually answer (pricing model, routing mode — business-side decisions). For pure-code blockers like type errors or FSD boundary violations, option A is usually faster.

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

Safety on option A

Picking A surfaces one more explicit confirmation:

Rolling back to:
a3f8c12 stripe webhook initial skeleton (3 hours ago)

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

git reset --hard only runs if you type yes. Anything else, or closing the prompt, does nothing. One more guard at this seat.

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

07-automated-safety-net.md describes how session-start.sh automatically lays files like active.md, progress.md, and saas-spec.md into the AI context on every new session. That hook drops raw content in — exactly as it sits in the files.

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

Mechanism	When	What you see
session-start.sh hook	Auto, on every new session	State files dumped in raw. The AI sees it; you do not
/resume command	When you explicitly call it	A one-screen summary: “current stage, last action, recommended next command”

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

The healthy shape — a single-screen summary

When you call the command, the output looks like this:

Current status

Stage: customized (branding and route tree painted)
Last action (2 days ago): paste Stripe Price ID into the Pro plan card
Features: 4 / 7 passing
Pace: novice
Routing mode: marketing-app
API adapter: edge-functions
MCPs: figma, supabase

Next action you wrote down (active.md)
"Write one e2e scenario for the checkout flow, then run /test-saas"

Natural next step
Continue the implement-billing area? I can walk you to the slash command.

The summary is shaped to land inside 20 lines. The whole picture fits one screen, so the next step is right there. Even when progress.md is long, only the last line or two get summarized.

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 “paste Stripe Price ID into the Pro plan card”, but the folder shape shows the pricing page skeleton has not even been generated 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, or a forgotten finish, can mix the two. The confirm is there for that.

How the two flow together in one cycle

The usual cycle of the two commands looks like:

1. Working, validation blocks twice (e.g. webhook signature check)
   → /recover-from-blocked → option A rolls back
   → You write a one-liner into active.md: "where stuck, what to try next"

2. Close the laptop, come back the next day
   → /resume → "where you got stuck yesterday and what to do next" fits one screen

3. Take the recommended slash command back into the same area
   → This time you wrote out more context up front, so it passes

You do not need to memorize both names. Stuck → first one. Lost → second one. Two seats, that is all.

When the commands do not run

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

• When you forked the base, the .claude/ folder did not come along. This is rare on a normal git clone, but possible if someone added .claude/ to .gitignore in the fork you received. From your folder, run ls .claude/skills/ and confirm the recover-from-blocked and resume directories are there.
• The slash command itself was typed differently. The exact strings are /recover-from-blocked and /resume. Extra spaces or uppercase letters do not get recognized.

Next

With the workflow safety net in hand, the prep is done for distribution. The four routes for getting your SaaS onto someone else’s browser sit in 08-distribution.md. Before that, the three automated safety nets — what each one does on its own — get covered in 07-automated-safety-net.md.