unstuck: break the AI fix loop

Signs of a loop: the same error after two or more attempts; fixes that move the error somewhere else; edits to files unrelated to the symptom; "this should work now" without anyone seeing it work; a growing pile of try/catch, retries, any, // @ts-ignore and commented-out code.

The rule that ends loops: no more edits until you can explain the bug with evidence.

1. Freeze and take stock (no code changes)

• Write a short ledger: the symptom (exact error text and where it appears: browser console, terminal, server logs, hosting logs), each attempt so far, and what happened after it.
• Run git status and git diff --stat. How much has changed since the last commit?
• Offer a checkpoint: git switch -c unstuck/<short-name> plus a commit, so nothing is lost and you can compare. Ask first. No git? Say so: it's the #1 safety net for AI coding. Offer git init.

2. Reproduce it

• Get the exact steps and the exact error. Read the full stack trace and find the top frame in their code, not the library's.
• Make sure you're reading the right log. Server errors don't show in the browser console; browser errors don't show in the terminal; production errors live in the hosting dashboard (Vercel → Logs, Netlify → Functions, Supabase → Logs).
• Shrink it to the smallest repro: one command, one curl, one page, one test.

3. Was it ever working?

• Yes: git log --oneline -20, find the last good commit, git diff <good>..HEAD --stat. Often the culprit jumps out. For a long history, use git bisect.
• Works locally but not deployed: compare env vars, build-time vs runtime vars, URLs and ports, CORS, cookie domain, Node/Python version, and whether the database migration ran in production.

4. Clear the pile

Leftover changes from failed attempts hide the real bug and add new ones. List them and, with the user's OK, revert the ones that didn't help (git restore -p, or go back to the checkpoint). Work from the last known-good state plus the minimum change.

5. Hypotheses, then experiments

• Write down up to 3 hypotheses. For each: the evidence for it, the evidence against it, and one cheap test that could prove it wrong (log a value, curl the endpoint, check the response in the Network tab, print the installed version).
• Run one experiment at a time. Change one thing. Look at the result. Revert it if it didn't help.
• Ground truth beats memory. Check the installed version (node_modules/<pkg>/package.json, pip show <pkg>) and that version's docs or type definitions before assuming an API exists. AI-written code often targets another version, or calls functions that never existed.

6. Usual suspects in AI-built apps

7. Escalate instead of looping

After two failed experiments, zoom out: re-read the original symptom, question the assumption about where the bug is, search the exact error message together with the library version, read the library's source or types, or rebuild the feature smaller from the last good commit. Tell the user plainly when you need something only they have: hosting logs, dashboard settings, the exact click path.

8. Fix, prove and report

Once the root cause is proven: make the minimal fix, show the repro passing, remove debug logs and leftover attempt code.

🧭 unstuck
Root cause: … (evidence: …)
Fix: … (files)
Proof: the repro now … (command or steps)
Cleaned up: reverted N leftover changes from earlier attempts
Avoid next time: …

Offer to add a one-line lesson to CLAUDE.md / AGENTS.md (for example "Supabase returns [] when RLS blocks: check policies before changing queries") so future sessions don't repeat the loop. Ask first.