For a month I tried to fix agent failures by improving instructions. It barely helped. Then I wrote a script that runs before the agent touches anything, and the failure count dropped hard.
The script is not clever. It checks six things.
1. What branch am I on, and is it clean?
git status plus the current branch, printed into the task context. Half my "the agent edited the wrong file" incidents were actually "the agent edited the right file on the wrong branch".
2. Which ports are already taken?
The agent starts a dev server, and it fails, or worse it silently attaches to something already listening. Print the ports in use before the task starts, and check again after. Twice I found a zombie process from my own earlier run holding the port, and the agent spent 20 minutes blaming the code.
3. Is anything left over from the last run?
Temp directories, lock files, half-written output, running background processes with names I recognise. Cleaning this is cheap; debugging around it is not.
4. Does the fixture still reproduce the problem?
If the task is "fix the failing test", the test must be failing before the agent starts. I have absolutely run a task where the bug was already gone and the agent invented a plausible cause for a failure that no longer existed.
5. Are the credentials and paths the ones I think they are?
Which database, which host, which token. Not the value - just an assertion that it is the expected one. One run pointed at a staging database because a shell profile had been changed somewhere else. Nothing broke, which is exactly why nobody noticed for two days.
6. Is the snapshot taken?
The one from my earlier post: hashes, key command outputs, and a copy of what is about to be modified. If this step fails, the task does not start. A task that cannot be undone should not begin.
Why a script and not a checklist
Because I skip checklists. Six checks in a script that refuses to proceed is 40 lines of bash and it never has a bad day. And it produces text I can paste into the task context, so the agent starts from facts instead of assumptions - the same facts I would have had to explain anyway.
The unexpected benefit: when something does go wrong, the pre-flight output is the first half of the postmortem. I can see the world as it was before the run, which is usually the exact state I need to compare against.
If you have one, what is in it that I am missing? Mine refuses to start on a dirty tree, which annoys me weekly and has saved me more than once.
Top comments (1)
One regression test I'd add: let run A pass preflight, then let run B take the selected port or change HEAD before A's first write. Does A stop, or proceed using the earlier snapshot?
That tests the gap between checking state and relying on it. A task-scoped lock can coordinate cooperating runs, but unrelated processes still need a fresh check. I'd also test that cleanup skips a temp directory or process owned by run B, even if it looks like leftovers from A.
These are proposed checks. I haven't run them against your script.