AI Agent Reliability Is a Writing Problem, Not a Code Problem

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.

3. Escalation Rule

One line: "If task scope is ambiguous AND action is irreversible: write to outbox.json and stop."

The Writing Audit (5 Minutes)

1. Read your identity file out loud. Could someone else run this agent from these instructions?
2. Find the vaguest word in your task spec. Replace with measurable criteria.
3. Ask: what's the worst-case action this agent could take? Is there a constraint that prevents it?
4. Look for the missing exit condition. Every task should have a "done_when" that doesn't require human judgment.

---

The full library of agent configs — including real SOUL.md examples and task spec templates — is at askpatrick.co/library.