What do you see?
Pick the closest one. Each goes to what to try first, the incident it looks like, and the ticket that teaches the fix.
- The agent keeps going in circles
- I deployed and the site is down, or still shows the old version
- It works on my machine, not on the server
- Connection error, or it can't reach an API
- Sign-in says OK but I'm not signed in
- The page loads but nothing responds to clicks
- It says saved, but the data isn't there
- All tests pass, but it's wrong
- Works for some inputs, wrong for others
- I hit usage limits
- It's costing more than I expected
- The agent deleted or killed something it shouldn't have
- I think a key or password leaked
- My fix disappeared
- Tests stopped running before deploys
The agent keeps going in circles
Try this first
- Stop it. Every new attempt on top of a broken one makes the next harder.
- Go back to your last good commit (
git restore .orgit reset --hard <commit>if you're sure). - Start a fresh session and give it three things: what you want, what you tried, the exact error. Ask for a plan before code.
Tickets that teach the fix
I deployed and the site is down, or still shows the old version
Try this first
- Ask the live site what it's running (
curlthe version endpoint or look at the footer). Don't trust the deploy job's colour. - Open the host's build log, not the agent. The real error is usually in the last 30 lines.
- Reproduce the build from a clean clone:
git clone . /tmp/check && cd /tmp/checkand build there.
It happened to us
- The deploy job was green and the site was down: Why "it works on my machine" survives into 2026, and the two commands that catch it.
- Healthcheck red, app perfectly fine: Why localhost isn't always local.
Tickets that teach the fix
It works on my machine, not on the server
Try this first
- Check that every file the build needs is committed:
git status --ignoredshows files git is ignoring. - Compare environment variables. An empty variable is not the same as a missing one.
- Run the same check inside the real container or host, not on your laptop.
It happened to us
- The deploy job was green and the site was down: Why "it works on my machine" survives into 2026, and the two commands that catch it.
- Connection error that wasn't the network: A one-line config bug that only exists in production.
- Healthcheck red, app perfectly fine: Why localhost isn't always local.
Tickets that teach the fix
Connection error, or it can't reach an API
Try this first
- Print the error's underlying cause, not just its message (
e.causein JavaScript,__cause__in Python). - Print the URL it's actually calling. Look for empty or wrong base URLs.
- Try the same request with
curlfrom the same machine.
It happened to us
- Connection error that wasn't the network: A one-line config bug that only exists in production.
Tickets that teach the fix
Sign-in says OK but I'm not signed in
Try this first
curl -ithe sign-in request and read theSet-Cookieheader itself.- Check the cookie's domain, path,
Secure(needs https) and whether the value looks quoted or cut. - Check the provider's allowed redirect URLs include the address you're on.
It happened to us
- Login returns 200 and the session never starts: The one command that would have saved an evening.
Tickets that teach the fix
The page loads but nothing responds to clicks
Try this first
- Open the browser console. A red error at load time usually explains it.
- Try the production build locally (build, then start), not the dev server.
- Only then look at the code.
It happened to us
- The page loads and no button does anything: When the bug isn't in your code at all.
Tickets that teach the fix
It says saved, but the data isn't there
Try this first
- Write one record and read it back from a different session or tool (database console, a second script).
- Don't trust counters or success messages the code prints about itself.
- Check whether something deletes or overwrites it later (rotation, cleanup jobs, migrations).
It happened to us
- 437 rows processed, zero results saved: Why a success counter is not evidence.
- The backup rotation deleted the only good backup: Why "keep the last 7" is a dangerous rule.
Tickets that teach the fix
All tests pass, but it's wrong
Try this first
- Ask who wrote the tests. If it was the same agent that wrote the code, they test what it already thought of.
- Write three cases from the spec yourself, combining conditions it lists separately.
- Or have a second agent write them without reading the code.
It happened to us
- The bot that graded its own homework: Why 40 green tests can mean nothing, and how to write the 41st that matters.
Tickets that teach the fix
Works for some inputs, wrong for others
Try this first
- Write down the failing input exactly, and the expected output.
- Look for order: rules checked in sequence where the first match wins.
- Turn the failing input into a test before fixing anything.
It happened to us
- The bot that graded its own homework: Why 40 green tests can mean nothing, and how to write the 41st that matters.
- The most expensive model gave the worst results: How to compare models without fooling yourself.
- The cause we found by elimination was wrong: How agents (and people) talk themselves into the wrong root cause.
Tickets that teach the fix
I hit usage limits
Try this first
- Count how many sessions and subagents are running right now.
- Use a cheaper model for mechanical work; keep the strongest for planning and review.
- Shorter rules files and fresh sessions reduce what every call has to read.
It happened to us
- Seven agents at once, quota gone by mid-morning: How to size parallel work.
Tickets that teach the fix
It's costing more than I expected
Try this first
- Look at the provider's usage page, not your own estimate. Check cached tokens separately.
- Find what gets reprocessed when you change a prompt.
- Log cost per task from now on.
It happened to us
- The bill didn't come from the volume: Where AI money actually goes.
- The most expensive model gave the worst results: How to compare models without fooling yourself.
- Seven agents at once, quota gone by mid-morning: How to size parallel work.
Tickets that teach the fix
The agent deleted or killed something it shouldn't have
Try this first
- Stop the session. Check
git statusandgit stash list; restore from your last commit. - If it killed a process, find out what it was before restarting things.
- Add a hook or permission rule so it can't happen twice.
It happened to us
- Freeing port 8000 shut down Docker: Why permissions and hooks exist.
Tickets that teach the fix
I think a key or password leaked
Try this first
- Rotate it at the provider now. Deleting the file doesn't remove it from git history.
- Check the provider's usage for anything you don't recognise.
- Add a secret scanner before commits.
It happened to us
- Secrets in git, across dozens of repos: Where secrets leak when an agent is doing the typing.
Tickets that teach the fix
My fix disappeared
Try this first
git log -p <file>shows who changed it back and when.- Look for automation that reverts or regenerates files: scripts, bots, other agents.
- Check two agents aren't working in the same folder.
It happened to us
- We rolled back a safety fix because a sentence changed: How an automatic safety net can be the thing that hurts you.
Tickets that teach the fix
Tests stopped running before deploys
Try this first
- Open the CI workflow file and read its last change (
git log -p .github/workflows). - Check what your own setup scripts commit.
- Make the deploy job depend on the test job.
It happened to us
- Our setup script replaced the CI that ran the tests: Your tooling is also a contributor that can be wrong.