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 a