22 of 36 agent failures traced back to my brief
Since late August I’ve been building DailyDen, a chore app for kids, with a small crew of AI agents. Claude Code runs the show. Meta’s Muse Code writes the app code, GPT-6 Astra paints the characters, Opus 5.5 draws the icons, and Fable 5.1 takes the heavy screen work.
When a run goes wrong and there’s something to learn, it gets a line in a lessons file. 305 tasks in, there are 36 lines. I went back and sorted them by who actually caused the problem.
22 of the 36 trace to my brief. 14 trace to the agent.
The first 14 runs were all me
About 3 weeks in, after 14 delegated runs and 11 landed tasks, I wrote this into the project’s instructions: every recorded failure so far was the orchestrator’s brief. The orchestrator is Claude writing the spec, from what I asked for. So, me.
Every one had the same shape: a claim about the system that I never checked.
I hoped that would wear off as the specs got better. It mostly didn’t; 22 of 36 is still a clear majority.
What a bad brief looks like
A few real ones:
- “Redraw those ten.” The list under it had 9 items. The agent had to guess the tenth.
- “Treat the visor like the celestial crown.” I meant the look. The agent copied where the crown sits, which is the top of the head, and the visor floated.
- Caps “wider” than today’s. A floor and no ceiling. All 9 attempts came out 159 to 175% of the head width, against a reference at 133%. My verdict at the time: “those look bad.”
- A browser check on
/style-studio. That page doesn’t exist. It’s a tab inside the app, so the check could never pass. - The worst case that was the best case. A brief told the agent to test text contrast against the lighter end of a gradient, calling it the worst case. A brighter background raises the contrast of dark text, so the lighter end was the easy case. The agent did what I said, and its test passed a color that actually fails, at 4.35:1.
None of these are hard. Each one was checkable in a minute, and I skipped the minute.
Sound familiar?
If you’ve briefed a designer, an agency, or a freelance writer, you’ve written some version of these. “Make it pop like the Nike ad.” “A few more options.” “Punchier.” The other person fills the gap with a guess, then everyone blames the draft.
Agents make it faster and cheaper to see. A person might push back on a list of 9 labeled ten. An agent (usually) builds what you wrote.
It’s the same rule as my note on copy: specificity beats superlatives. A brief is copy with one reader.
The 14 that were the agent’s
These had patterns too. 5 were a write-up that said more than the work did: a “0 problems” report next to a file that listed 2, a fix claimed for a bug that turned out to live in the agent’s own test setup, a missed goal filed under a page of passing numbers. 3 were tests that couldn’t fail, so they passed whether the code worked or not.
So I read the agent’s summary last. A separate reviewer, starting with a clean context, reads the actual change against the brief, then checks the summary against the change.
What I changed
- The best model goes on the brief. Writing the spec is where model strength pays. Running the script, reading the diff, and writing the commit are mechanical, and a cheaper model does them fine.
- Run what you assert. If a brief says the checks will pass, or that an image comes out 1024 by 1024, run the command first. Both of those were wrong once.
- Turn “like X” into a number. A placement brief now names the landmark and the tolerance: where the band’s lower edge sits, measured from the eyes, with a range. “Like the crown” leaves the agent to guess which part of the crown you meant.
- Repeat offenders become rules. A reviewer once undid the very fix it was reviewing, so now a hook blocks the reviewer from writing to the project at all. A rule that’s enforced doesn’t need remembering.
This site runs on a smaller version of the same setup now. Every change starts as a written brief with its own checklist, gets checked by a reviewer that didn’t write it, and lands on a staging copy before I publish.
The bottleneck is the person writing the instructions, which is good news, because that’s the part I can fix.
Hiring a marketer who builds? Get in touch.