Lessons Toolkit Final Test Certificates Verify

← The Architect's Toolkit

The Architect's Toolkit

Troubleshooting Playbook

When something breaks, find the symptom and copy the fix prompt into your AI builder.

Loading your toolkit…

7 groups, 30 fixes. Search matches the symptom, the cause, and the fix prompt.

Claude Code and your project

You asked for one small change and Claude Code edited a bunch of other files you never mentioned. Now something that used to work is broken.

Likely cause: The request was open-ended, so Claude Code guessed at the wider intent and touched more than you wanted. It is doing what it thinks you meant, not what you actually need.

Fix prompt

Paste this into your AI builder:

You changed more than I asked for and now [WHAT BROKE] is broken. Show me every file you touched in your last change, explain in plain words what each edit did, and then undo only the parts that were not about [THE ONE THING I ACTUALLY ASKED FOR]. Leave the rest exactly as it was before.

Claude Code stopped partway through a task. Some files are half-written, the app does not run, and you are not sure what is finished and what is not.

Likely cause: A long task got cut off before it was done. The project is now in a half-changed state, which is why it will not start.

Fix prompt

Paste this into your AI builder:

Your last task stopped before it was finished and the app no longer runs. First, look at what you have changed so far and tell me in plain words what is done and what is still missing. Then finish the job so [WHAT I ASKED FOR] works end to end, and run the app to confirm it starts cleanly before you tell me you are done.

Claude Code added features, files, or libraries you never asked for. The project feels heavier and more confusing than it needs to be.

Likely cause: Claude Code tried to be helpful and built ahead of your request, adding things it assumed you would want next.

Fix prompt

Paste this into your AI builder:

In your last change you added [WHAT YOU NOTICED, e.g. a new page / a new library / extra settings] that I did not ask for. List everything you added beyond my original request, then remove the parts I do not need so the project only contains [WHAT I ACTUALLY ASKED FOR]. Do not add anything new while you clean this up.

The last round of changes made things worse and you just want to go back to how the project was a little while ago.

Likely cause: Recent edits broke something and there is no clean way to pick the changes apart by hand. The fastest path is to roll back to a known-good point using git, which keeps a history of every save.

Fix prompt

Paste this into your AI builder:

I want to undo the recent changes and go back to how the project was [WHEN IT LAST WORKED, e.g. before today / before the payments work]. Use git to show me the recent save points with short descriptions, help me pick the last one where everything worked, and roll the project back to exactly that point. Explain what I will lose so I can confirm before you do it.

Claude Code insists it made a change, but you cannot see any difference when you run the app.

Likely cause: The edit may have landed in the wrong file, or the running app is showing an old cached version instead of the new code.

Fix prompt

Paste this into your AI builder:

You said you changed [WHAT YOU EXPECTED TO SEE], but I see no difference when I run the app. Show me the exact file and lines you changed, confirm that file is the one the app actually uses, then stop and restart the app from scratch so I am looking at the newest version. Tell me exactly what I should see now.

Build and deploy

The app runs fine on your own computer, but the deploy fails or the live site shows an error.

Likely cause: Your computer has settings, files, or secrets that the hosting platform does not. Usually it is a missing environment variable, a file that was never uploaded, or something that only exists on your machine.

Fix prompt

Paste this into your AI builder:

My app works when I run it locally but the deploy to [WHERE I DEPLOY, e.g. Vercel] is failing. Read the deploy error message here: [PASTE THE ERROR]. Compare what my local setup has against what the live deploy has, point out anything that exists only on my computer (like environment variables or files git is ignoring), and tell me exactly what I need to add on the hosting side to make the live version match.

Everything was fine until you added a new package or library, and now the build will not finish.

Likely cause: The new package may be the wrong version, may clash with something already installed, or may need a setup step that was skipped.

Fix prompt

Paste this into your AI builder:

The build broke right after I added [NAME OF THE PACKAGE]. Here is the error: [PASTE THE ERROR]. Tell me in plain words whether this package is the cause, whether it clashes with something already in the project, and whether it is safe and well known. Then either finish setting it up correctly or remove it cleanly and suggest a safer alternative for [WHAT I WANTED IT FOR].

A feature that uses a key or secret works locally but is dead on the live site, often with a vague error or a blank result.

Likely cause: Your secret lives in a local .env file that never gets uploaded. The live site has no copy of it, so the feature that needs it cannot run.

Fix prompt

Paste this into your AI builder:

[WHICH FEATURE, e.g. the AI generation] works locally but does nothing on the live site. I think an environment variable is missing in production. List every environment variable my app expects, tell me which ones the live deploy needs to have set, and give me the exact names to add in my hosting dashboard. Do not show me the secret values, just the names.

You deployed a change but the live site still shows the old version.

Likely cause: Either the deploy did not actually finish, or the browser and the CDN are serving a cached copy of the old site.

Fix prompt

Paste this into your AI builder:

I deployed a change but the live site still shows the old version of [WHAT SHOULD HAVE CHANGED]. Check whether my latest commit actually deployed successfully, and if it did, explain how to clear the cached old version so I and my visitors see the new one. Walk me through how to confirm the new version is really live.

Environment variables and secrets

You set an API key, but the app acts like it is missing, blank, or wrong.

Likely cause: The app is looking for the key under a name that does not match what you saved, or the key is in the wrong file, or the app was not restarted after the key was added.

Fix prompt

Paste this into your AI builder:

My app is not reading the [WHICH KEY, e.g. AI API] key, even though I added it. Show me the exact name the code expects, confirm it matches the name in my .env file character for character, check the key is in the right file, then restart the app so it picks up the change. Tell me how to confirm the key is being read without printing the key itself.

You realize a real API key or password got committed and pushed to GitHub.

Likely cause: The secret was written into a file that git tracks, so it is now in your history. Even after you delete it from the current code, old commits still contain it, and bots scan public repos for exactly this.

Fix prompt

Paste this into your AI builder:

I think I committed a real secret to git. The key is [WHICH KEY, e.g. my AI API key] and it is in [FILE NAME IF YOU KNOW IT]. Treat that key as already leaked: tell me step by step how to revoke and replace it at the provider first, then move it into my .env file, add that file to .gitignore so it never gets committed again, and explain what it would take to scrub it from my git history.

Your .env file exists and looks correct, but none of the values seem to load.

Likely cause: The file might be named or placed wrong, the app might not be set up to read it, or there are stray quotes and spaces around the values.

Fix prompt

Paste this into your AI builder:

My .env file exists but none of its values are loading. Confirm the file is named exactly right and sitting in the folder the app reads from, check that the app is actually set up to load a .env file, and look for stray quotes or spaces around the values that could break them. Fix whatever is wrong and show me one safe test that proves the values are loading now.

You are setting up the app on a new machine or a fresh deploy and have no idea which secrets it needs.

Likely cause: The list of required secrets lives scattered through the code, and there is no single checklist of what to provide.

Fix prompt

Paste this into your AI builder:

I am setting up this project [WHERE, e.g. on a new computer / on a fresh deploy] and need to know every secret it requires. Scan the project and give me a plain checklist of every environment variable, what each one is for, and where I get the value. If there is an example env file, point me to it. Do not print any real secret values.

AI output

Sometimes the AI returns a garbled or unexpected response and the page crashes or goes blank instead of showing a result.

Likely cause: The code assumes the AI always answers in a perfect, expected shape. When the AI returns something messy or incomplete, the code chokes on it and the whole page falls over.

Fix prompt

Paste this into your AI builder:

When the AI returns a messy or unexpected response, [WHERE IT BREAKS, e.g. the trip results page] crashes or goes blank. Add a safety net around the AI response so that if it comes back malformed or empty, the app shows a calm message like 'We could not generate that, please try again' instead of crashing. Log the bad response somewhere I can inspect it later, and make sure the rest of the page keeps working.

Your AI bill is climbing faster than expected and you are not sure why.

Likely cause: There may be no limit on how often each person can call the AI, the app may be sending more than it needs in each request, or it may be using a pricier model than the task requires.

Fix prompt

Paste this into your AI builder:

My AI bill is climbing and I want to understand and control it. Show me everywhere the app calls the AI, tell me roughly what each call costs and what is driving the spend, then add sensible limits so a single user cannot run up the bill. Where the task is simple, suggest a cheaper model. Keep the quality of [THE MAIN FEATURE] good while cutting waste.

AI responses take a long time and users stare at a spinner, sometimes long enough that the request times out and fails.

Likely cause: The app waits for the entire AI answer before showing anything, and long answers can run past the time limit the hosting platform allows.

Fix prompt

Paste this into your AI builder:

AI responses in [WHICH FEATURE] feel slow and sometimes time out. Change it so the answer streams in piece by piece as it is generated, so the user sees progress immediately instead of a frozen spinner. Make sure a long response cannot exceed the hosting platform's time limit, and show a clear message if it does fail. Explain what you changed in plain words.

The AI mostly works, but every so often it formats its answer differently and a part of your app misreads it.

Likely cause: The AI is being asked for a result in plain prose, so its exact shape varies. The code expects a fixed structure and breaks when the shape drifts.

Fix prompt

Paste this into your AI builder:

The AI in [WHICH FEATURE] usually works but sometimes formats its answer differently and the app misreads it. Make the AI return its answer in a strict, fixed structure every time, and have the app reject and retry once if the answer does not match that structure. Show me a calm fallback message for when it still fails after the retry.

Payments and webhooks

A user paid, the charge went through on the payment provider, but in your app they still show as a free user.

Likely cause: Your app finds out about payments through a webhook, a message the payment provider sends your server. If that message never arrived or was not handled, your app never flipped the user to paid.

Fix prompt

Paste this into your AI builder:

A user paid through [WHICH PROVIDER, e.g. Creem / Stripe] but my app still shows them as free. Walk me through how a successful payment is supposed to flip a user to paid in my code, check whether the webhook that does this actually fired and was handled, and find where the chain broke. Then show me how to safely mark this specific user as paid and prevent it happening to the next person.

Payments happen, but your webhook endpoint never seems to receive anything.

Likely cause: The webhook is probably pointed at the wrong URL, or the provider is not configured to send the events you care about, or your endpoint is rejecting the messages.

Fix prompt

Paste this into your AI builder:

My payment webhook never seems to receive anything from [WHICH PROVIDER]. Tell me the exact URL my webhook endpoint is at on the live site, what events I need the provider configured to send, and how to test that a message actually reaches my server. Check that my endpoint is not secretly rejecting valid messages, and explain how to read the provider's delivery log to see what happened.

Your test payments fail or behave strangely, or a real card got charged during testing.

Likely cause: You are likely mixing up test mode and live mode, using a real card in test mode or test card numbers in live mode, or your keys do not match the mode you are in.

Fix prompt

Paste this into your AI builder:

My test payments with [WHICH PROVIDER] are behaving wrong and I am not sure if I am in test mode or live mode. Confirm which mode my current keys are for, tell me the correct test card numbers to use in test mode, and make sure I am never using a real card against test mode or a test card against live mode. Explain how to switch safely between the two.

A webhook seems to run twice, so a user gets granted access twice or appears to be charged or upgraded more than once.

Likely cause: Payment providers can send the same webhook message more than once on purpose. If your code does not recognize a repeat, it does the work twice.

Fix prompt

Paste this into your AI builder:

My payment webhook from [WHICH PROVIDER] sometimes runs twice and [WHAT HAPPENS, e.g. the user gets upgraded twice / counted twice]. Make my webhook handler safely ignore a message it has already processed, so running it twice has the same result as running it once. Explain in plain words how you made it safe to receive duplicates.

Database

Users create data, but after you redeploy the app, everything they saved is gone.

Likely cause: The data is being saved to a file on the server's disk instead of a real database. When the app redeploys it gets a fresh, empty copy, so everything written to disk vanishes.

Fix prompt

Paste this into your AI builder:

My users' data disappears every time I redeploy. I think it is being saved to a file on the server instead of a real database. Confirm where [WHAT DATA, e.g. trips] is currently stored, then move it into a proper database so it survives redeploys. Migrate any data I can still recover, and explain how I confirm it now persists across a redeploy.

You changed the shape of your data, the migration failed partway, and now the app errors because the database does not match what the code expects.

Likely cause: A migration is a change to the database structure. When it stops halfway, the database is left in a mixed state that no longer lines up with the code.

Fix prompt

Paste this into your AI builder:

A database migration failed partway and now my app errors because the database does not match the code. Here is the error: [PASTE THE ERROR]. Tell me in plain words what state the database is in now, then either safely finish the migration or roll it back to a clean known state. Before you run anything destructive, tell me what data could be affected so I can confirm.

Two people saved at almost the same time and one person's change silently wiped out the other's.

Likely cause: Both saves read the same starting data, then wrote on top of each other. The second write did not include the first person's change, so it overwrote it.

Fix prompt

Paste this into your AI builder:

When two users save [WHAT DATA] at nearly the same time, one person's change overwrites the other's. Change how saves work so two near-simultaneous writes cannot silently clobber each other, and so each user only ever updates their own records. Explain the fix in plain words and how I can test that the overwrite no longer happens.

As your data grows, pages that load lists or look things up get slower and slower.

Likely cause: The database is scanning through everything to find what it needs because there is no index, the equivalent of reading a whole book instead of using its index.

Fix prompt

Paste this into your AI builder:

My [WHICH PAGE OR FEATURE] gets slower as data grows. Find the database lookups behind it, tell me which ones are scanning everything instead of jumping straight to the right rows, and add the indexes needed to speed them up. Explain what an index does here in plain words and confirm the page is faster after the change.

Auth

Logged-in users can see other people's data, not just their own.

Likely cause: The app checks that someone is logged in, but does not check that the data they are asking for actually belongs to them. Identity works; ownership is not enforced.

Fix prompt

Paste this into your AI builder:

Logged-in users can see other people's [WHAT DATA, e.g. trips], not just their own. Go through every place the app reads or changes user data and make sure it only ever returns or touches data that belongs to the currently logged-in user. Treat the logged-in user's id as the source of truth, never an id passed in from the browser. Show me how you locked each one down.

After logging in, the page keeps bouncing back to the login screen over and over in a loop.

Likely cause: The app logs the user in, but the next page does not recognize them as signed in, so it sends them back to log in again, and the loop repeats.

Fix prompt

Paste this into your AI builder:

After I log in, the app keeps bouncing me back to the login screen in a loop. Trace what happens right after a successful login, find why the next page does not recognize me as signed in, and fix it so a logged-in user lands on [WHERE THEY SHOULD GO, e.g. their dashboard] and stays there. Explain in plain words what was causing the loop.

A page that should require login can be opened by anyone who knows the URL.

Likely cause: The page is only hidden in the menu, not actually protected. There is no check that blocks a signed-out visitor from loading it directly.

Fix prompt

Paste this into your AI builder:

The [WHICH PAGE] page is supposed to require login but anyone who types the URL can open it. Add a real check so that a signed-out visitor is sent to the login screen before that page loads, on the server side, not just hidden from the menu. Then list every other page that should be protected and confirm each one is actually locked down.

Your pages require login, but the behind-the-scenes data requests can still be called by anyone.

Likely cause: Protection was added to the visible pages but not to the data endpoints behind them. Someone can skip the page entirely and hit the data directly.

Fix prompt

Paste this into your AI builder:

My pages require login but I think the behind-the-scenes data requests are not protected. Go through every data endpoint in the app and make sure each one checks that the caller is logged in and is only allowed to touch their own data, before doing anything. List every endpoint you checked and which ones were exposed.

Users log in successfully but the app keeps treating them as logged out on the next visit or after a refresh.

Likely cause: The signed-in session is not being remembered between visits, often a cookie or session setting that does not survive a refresh or does not work on the live domain.

Fix prompt

Paste this into your AI builder:

Users log in fine but the app forgets them after a refresh or on their next visit. Look at how the logged-in session is stored and find why it does not survive a refresh or the live domain. Fix it so a logged-in user stays logged in until they sign out, and explain in plain words what was dropping the session.