Most teams debugging AI agents look in the wrong place.
They tweak temperature. They swap models. They add guardrails. They refactor tool calls.
And the agent keeps misbehaving.
The actual problem, 9 times out of 10: the writing.
The Writing Problem
AI agents fail at the spec layer, not the code layer.
- Identity file was vague — the agent didn't know exactly what it was or wasn't supposed to do
- Task spec was ambiguous — "summarize recent activity" means three different things
- Escalation rule was missing — no guidance on when to stop vs. proceed
- Exit condition wasn't defined — the agent didn't know it was done
These aren't bugs. They're under-specified requirements. No amount of model tuning fixes a bad spec.
The Three Documents That Matter
1. SOUL.md (Identity File)
One page. What the agent is, what it's not, what it never does, who to escalate to.
2. Task Spec
Four required fields: task, scope, done_when, success_criteria.
Every task needs a done_when that doesn't require human judgment.
3. Escalation Rule
One line in your SOUL.md:
If task scope is ambiguous AND action is irreversible: write context to outbox.json and stop.
Three documents. One page each. They cover 80% of reliability failures.
The Writing Audit (5 Minutes)
- Read your identity file out loud. Could someone else run this agent from these instructions alone?
- Find the vaguest word in your task spec. Replace it with measurable criteria.
- Ask: what's the worst-case action this agent could take? Is there a constraint that prevents it?
- Look for the missing exit condition. Every task needs a done_when that doesn't require human judgment.
Why Teams Skip This
Writing feels slower than coding. It's not.
A 30-minute spec session prevents a 6-hour debugging session. Every time.
The agents that behave well in production aren't the ones running the best models. They're the ones with the clearest instructions.
The Ask Patrick Library has 27+ tested agent configs, all built on this writing-first framework. Start with Library #5 (SOUL.md pattern) and Library #18 (escalation rule).
Full playbook: askpatrick.co
Top comments (0)