Use it when: Something is broken and you can describe what you expected versus what happened. Use it instead of "fix this".
Prompt · replace every [BRACKET] first
Read AGENTS.md first.
Bug: [what you did] -> [what you expected] -> [what happened instead].
Error text, if any (copied exactly):
[paste error or "none"]
Work in this order and don't skip ahead:
1. Reproduce it. Tell me the exact steps or command that shows the bug, and what output proves it's happening.
2. Find the cause. Name the file and line, and explain in 2-3 plain sentences why it happens. If you have more than one theory, list them, most likely first, and say how you ruled the others out.
3. Fix only the cause. Smallest change that works. No refactors, no new dependencies.
4. Prove it. Re-run the reproduction and show it now passes. Run lint, type check and tests.
5. Report: files changed (one line each), how you verified it, and anything you're unsure about.
If you can't reproduce it, stop after step 1 and tell me what you tried and what extra info you need.
Why it works: Agents that patch before reproducing tend to fix a symptom and break something nearby. Forcing a reproduction first gives the agent (and you) proof the fix actually worked.
Debugging
Error log triage
Use it when: You have a wall of red text (stack trace, build log, browser console) and don't know which line matters.
Prompt · replace every [BRACKET] first
Read AGENTS.md first. Don't change any code yet.
Here is the full log, unedited:
```
[paste the whole log]
```
1. Quote the one line that is the real root error (not a follow-on error), and explain in plain English what it means.
2. Point to the file and line in OUR code where it starts (ignore library internals unless the cause really is there).
3. Give me the 3 most likely causes, most likely first, each with one quick check I can run or you can run to confirm it.
4. Run those checks yourself if you can, then tell me which cause it is.
5. Propose a fix and wait for my OK before editing anything.
Why it works: Long logs make agents latch onto the last error, which is usually a side effect. Asking for the first real error plus a ranked list of causes with checks turns guessing into a short elimination.
Debugging
Loop breaker
Use it when: The agent has "fixed" the same bug two or three times and it keeps coming back, or it keeps undoing its own changes.
Prompt · replace every [BRACKET] first
Stop editing. We're in a loop.
Before you touch any more code:
1. List every fix you've tried for this so far, and what happened after each one.
2. Tell me what those failures prove is NOT the cause.
3. List assumptions you've been making that you haven't actually verified (versions, env vars, which file is really running, cached builds, the data in the database).
4. Pick the single assumption most likely to be wrong and tell me how to check it with one command or one log line.
5. Run that check and report what it shows.
Then propose ONE new approach that is different in kind from what you've already tried, not a variation of it. Wait for my OK before you make changes. If you think the honest answer is "I need information I don't have", say exactly what it is.
Why it works: Loops usually come from one wrong assumption the agent never re-checks. Making it write down what failed and what it assumed breaks the pattern, and stopping for approval stops it piling more edits on top.
Shipping
Deploy failure fix
Use it when: It works on your machine (or in the builder's preview) but the deploy on Vercel, Netlify, Cloudflare, Railway or Render fails, or the live site shows a blank page.
Prompt · replace every [BRACKET] first
Read AGENTS.md first.
It works locally but fails on [hosting provider].
Deploy log or live error (unedited):
```
[paste]
```
Check these in order and tell me what you find for each before fixing anything:
1. Build command, output directory and Node/Python version the host uses vs. what the project needs (package.json engines, .nvmrc, runtime files).
2. Environment variables: list every one the code reads, and mark which are missing or named differently on the host. Remember that client-side variables often need a prefix (NEXT_PUBLIC_, VITE_, etc.).
3. Case-sensitive import paths (works on Mac/Windows, fails on Linux).
4. Code that only works locally: localhost URLs, files written to disk, dev-only dependencies used at runtime.
5. Lockfile and package manager mismatches.
Then: run the production build locally (`[npm run build]`) and confirm it passes, make the smallest fix, and give me the exact settings I need to change in the host dashboard (if any) as a checklist. Never put secret values in the code or the reply.
Why it works: Most "works locally, fails on deploy" bugs fall into the same handful of buckets. A fixed checklist stops the agent rewriting app code when the real fix is a missing env var or a dashboard setting.
Refactoring
Safe refactor
Use it when: A file has grown into a monster (500+ lines, copy-pasted blocks) and you want it cleaner without breaking anything.
Prompt · replace every [BRACKET] first
Read AGENTS.md first.
Refactor [file or folder]. Goal: [easier to read / split into smaller pieces / remove duplication]. Behavior must not change at all: same inputs, same outputs, same UI.
Rules:
1. First, tell me how we'll know nothing broke. If tests don't cover this code, write a few tests that pin down what it does TODAY (including any weird behavior) and get them passing before you refactor.
2. Give me a plan of small steps. Each step should leave the app working.
3. Do one step at a time. After each step, run the tests and the type check.
4. No new features, no bug fixes, no dependency changes, no renaming of anything other files import, unless I approve it. If you spot a bug, list it at the end instead of fixing it.
5. Finish with a before/after summary: what moved where, and the test results.
Why it works: Refactors go wrong when behavior changes sneak in alongside the cleanup. Pinning current behavior with tests first, then moving in small verified steps, makes it reversible at every point.
Refactoring
Tests for code you didn't write
Use it when: Your AI-built app has zero tests and you're scared to change anything. Run this on the most important flow first (signup, checkout, saving data).
Prompt · replace every [BRACKET] first
Read AGENTS.md first.
Add tests for [feature or file, e.g. "the signup flow" or "src/lib/cart.ts"]. Don't change any app code.
1. Read the code and list what it currently does as plain-English rules ("If the email is already taken, it shows 'Account exists'"). Include edge cases: empty input, wrong types, network errors, logged-out users.
2. Use the test setup we already have ([test framework]). If there is none, suggest the lightest option for our stack and wait for my OK before installing anything.
3. Write tests that pass against the CURRENT code. If you find behavior that looks like a bug, still test what it does now, mark the test with a "BUG?" comment, and list it for me.
4. Run the tests and show me the results.
5. Tell me which important paths are still untested.
Why it works: "Characterization" tests record what the code really does, not what it should do, so they catch any change. They're the safety net that makes every other prompt in this pack less risky.
Shipping
Pre-ship security and sanity review
Use it when: Before you share the link with real users, or before every launch. Pair it with the pre-deploy checklist in this pack.
Prompt · replace every [BRACKET] first
Read AGENTS.md first. This is a review: don't change code until I approve a fix list.
Review this app as if it's about to get its first 1,000 strangers. Check:
1. Secrets: any API keys, tokens or passwords in the code, in git history, or sent to the browser? Which env vars are exposed to the client?
2. Auth: can a logged-out user reach pages or API routes they shouldn't? Can user A read or change user B's data by changing an ID in the URL or request?
3. Database: are access rules (e.g. row-level security) on for every table that holds user data?
4. Input: anywhere user input goes into a query, HTML, a file path or a shell command without validation?
5. Costs: any endpoint that calls a paid API (AI, email, SMS) with no login or rate limit?
6. Errors: do error messages leak stack traces or internal details to users?
7. Basics: 404 page, broken links, forms that fail silently, missing loading or error states.
Output a table: issue, severity (critical / high / medium / low), file and line, and the suggested fix. Critical first. Then wait for my OK on which ones to fix.
Why it works: AI builders ship working features fast but rarely check who else can call them. These seven areas cover the mistakes behind most painful launch-day surprises: leaked keys, open data, and surprise API bills.
Shipping
Session save (handoff)
Use it when: At the end of every work session, or before switching tools or models. It keeps the next session from starting cold.
Prompt · replace every [BRACKET] first
We're wrapping up this session. Don't change any app code.
Update AGENTS.md:
1. Under "Known gotchas", add anything we tripped over today that would trip up the next session (one line each). Don't duplicate what's already there.
2. Under "Commands" or "Project map", fix anything that's now out of date.
3. Under "Progress log", add one line at the top for today: what got done, and the next step.
Then give me a short handoff note I can paste into a fresh chat:
- What we were working on and where it stands
- What's verified working vs. not yet verified
- Open questions and known bugs
- The exact next step
Show me the AGENTS.md diff before saving it.
Why it works: Context dies when a chat ends or you switch tools. Writing it back into AGENTS.md is the "save file" from The Drop #1's quest: your next session, or your next tool, picks up where you left off.