pal-e-docs

Convention: Escalation Triggers

convention-escalation-triggers Convention

active convention agent
Project

Convention: Escalation Triggers

Defines when agents must stop autonomous work and escalate. The rule: if you're unsure whether to escalate, escalate. The cost of a false escalation is one message. The cost of a missed escalation is broken infra or lost work.

Immediate Escalation (Stop Everything)

These trigger an immediate halt. Do not attempt self-correction. Escalate with full context.
Trigger Why Escalate To
<strong>Destructive action required</strong> Any L0 action (see convention-agent-autonomy-levels). Irreversible. Lucas
<strong>Unknown failure — no recovery SOP</strong> If no SOP covers the failure mode, the agent doesn't have the knowledge to self-correct safely. Ava (agents) / Lucas (Ava)
<strong>Data loss risk</strong> Anything that could destroy data: DROP, DELETE, rm -rf, force push, PVC deletion. Lucas
<strong>External system interaction</strong> Email, Slack, anything outside Forgejo/pal-e-docs/repos. Agents cannot represent Lucas externally. Lucas
<strong>Security boundary crossed</strong> Secrets exposed, permissions changed, network rules modified. Lucas

Conditional Escalation (Try Recovery First)

These allow one self-correction attempt using the matching recovery SOP. If the SOP's recovery steps don't resolve it, escalate.
Trigger Recovery SOP Max Retries Then Escalate To
CI pipeline failure <code>sop-ci-pipeline-recovery</code> 2 Ava
Deploy failure <code>sop-deploy-recovery</code> 1 Ava → Lucas
Hook blocks unexpectedly <code>sop-hook-block-recovery</code> 1 Ava
MCP server failure <code>sop-mcp-server-recovery</code> 1 Ava
PR rejected by QA <code>sop-pr-rejection-recovery</code> 2 Ava
Database migration failure <code>sop-db-migration-recovery</code> 0 (escalate immediately) Lucas

Scope Escalation (Work Exceeds Boundary)

These don't indicate failure — they indicate the work has grown beyond what was planned.
Trigger What To Do Escalate To
<strong>Discovered work exceeds phase boundary</strong> Document the discovered scope. Complete current work. Flag the excess as a TODO or epilogue nit. Ava
<strong>Conflicting SOPs</strong> Two SOPs give contradictory guidance. Document both and which you'd follow. Ava → Lucas
<strong>3+ retry attempts exhausted</strong> Agent has been trying variations for >3 attempts. Diminishing returns. Fresh eyes needed. Ava
<strong>Blocking dependency discovered</strong> Work requires something that doesn't exist yet (missing API, missing infra, missing SOP). Ava

Escalation Format

When escalating, always include:
  • What happened — the error, the situation, the conflict
  • What I tried — recovery steps attempted, results
  • What I think should happen — your recommendation (agents should have an opinion)
  • What's blocked — downstream impact if this isn't resolved

Escalation Chain

Dottie escalates to Ava, not Lucas. Dev and QA escalate to Ava. Only Ava escalates directly to Lucas.
  • convention-agent-autonomy-levels — what's L0/L1/L2
  • convention-validation-checkpoints — verification loops
  • sop-ci-pipeline-recovery — CI failure recovery
  • sop-deploy-recovery — deploy failure recovery
  • sop-hook-block-recovery — hook block recovery
  • sop-mcp-server-recovery — MCP server failure recovery
  • sop-pr-rejection-recovery — PR rejection recovery
  • sop-db-migration-recovery — database migration recovery