The One-Line Fix That Cuts Agent Bugs by 80%: Add an Escalation Rule

#ai #devops #agents #programming

Most AI agent bugs aren't model failures. They're escalation failures.

The agent hit an ambiguous situation, couldn't resolve it, made its best guess, and kept going. The guess was wrong. Now you have a downstream mess.

The Pattern

Every agent needs one explicit rule:

"If uncertain about the right action, stop. Write context to outbox.json. Do not proceed."

That's it. One line in your SOUL.md or system prompt.

Why It Works

Without an escalation rule, agents optimize for appearing to succeed. They complete tasks. They produce output. The output is wrong — but by the time you find out, the agent has already moved on to the next task.

With an escalation rule, agents optimize for honest stopping. When they hit a wall, they create a recoverable pause instead of an unrecoverable mistake.

What Goes in outbox.json

At minimum:

{
  "timestamp": "2026-03-09T01:45:00Z",
  "agent": "suki",
  "task": "post Monday newsletter",
  "uncertainty": "Buttondown API returned 429 — unclear if post went through or was rate-limited",
  "last_known_state": "draft created, send_attempt made",
  "recommended_action": "check Buttondown dashboard before retrying"
}

Three fields matter most:

What the agent was doing (task context)
What it's uncertain about (specific decision point)
Last known good state (so recovery is possible)

The Results

When we added this pattern to our agents at Ask Patrick, the behavioral change was immediate:

Silent wrong-guesses dropped ~80%
Failures became visible instead of buried
Recovery time shrank because context was preserved

The agent doing less turned out to be the agent doing better.

Implementation

In your SOUL.md or system prompt, add a section like this:

## Escalation Rule
If you encounter a situation where you are uncertain which action is correct, or where proceeding risks unrecoverable state:
1. STOP. Do not guess.
2. Write a structured entry to outbox.json with: task, uncertainty, last_known_state, recommended_action.
3. Return control to the orchestrator or end the session.

An honest stop is always preferable to a confident mistake.

The Bigger Principle

Most agent reliability problems are spec problems, not model problems. The model will do exactly what you ask. The question is whether you've specified what to do at the edges.

Edge cases are where agents fail. Escalation rules are how you make those failures graceful.

We use this pattern across all five agents at Ask Patrick. Full config examples in the Library → askpatrick.co