The Escalation Rule: The One Config Change That Made Our Agents Actually Useful

Source: Dev.to

What Happens Without an Escalation Rule

Every time the agent hit a situation it wasn’t sure about — ambiguous data, conflicting instructions, edge cases outside its scope — it did its best and kept going.

“Doing its best” meant guessing. And those guesses stacked up silently.

The agent looked healthy. Logs showed activity. Tasks were completing. But the outputs were quietly wrong in a dozen small ways we didn’t catch until they compounded.

The Fix: One Line

If uncertain about how to proceed, stop. Write current context, the uncertainty, and attempted approaches to outbox.json. Do not continue until reviewed.

That’s it. One rule added to the agent’s SOUL.md.

What Changed

After adding the escalation rule:

• Silent errors dropped ~80%
• The agent’s “mistakes” became visible, reviewable, and fixable
• We caught three categories of edge cases we hadn’t designed for
• Debug time dropped because we knew exactly where the agent got stuck

Before: Agent produces wrong output, we find out from downstream effects or user complaints.
After: Agent stops at the point of uncertainty, writes context, we review and fix the edge case.

The outbox.json Schema

When the agent escalates, it writes to outbox.json:

{
  "timestamp": "2026-03-09T10:30:00Z",
  "task": "process Q1 revenue summary",
  "uncertainty": "found two conflicting totals in input files",
  "attempted_approaches": [
    "checked both files — different values for same line item",
    "checked timestamps — both recent, no clear winner"
  ],
  "context_snapshot": "state/current-task.json",
  "awaiting_review": true
}

The outbox file surfaces the problem without destroying the agent’s current context. You can review, fix the input, and restart cleanly.

Why This Works

Agents fail silently because they have no protocol for uncertainty. They’re designed to complete tasks, so they complete them — even when they shouldn’t.

The escalation rule gives the agent a third option beyond “complete” and “error”: stop and surface.

Loud, structured stops are always better than silent wrong completions.

The SOUL.md Rule Template

ESCALATION RULE:
If uncertain about how to proceed and confidence is below threshold:
  1. Stop current task execution
  2. Write to outbox.json: task, uncertainty, attempted approaches, context snapshot path
  3. Set awaiting_review: true
  4. Do not continue until outbox is cleared

Confidence threshold: cannot determine correct action from available context

One More Thing

The escalation rule pairs with a circuit breaker. If your agent keeps hitting the same edge case, the circuit breaker stops the loop. The escalation rule surfaces why.

Together they turn silent failures into visible, fixable problems.

Full pattern (with confidence thresholds and multi‑agent escalation chains): askpatrick.co/library/18