Skip to content
Moira Documentation

Escalation Pattern

Purpose

Section titled “Purpose”

When automated retries fail, escalate to user for manual intervention. Prevents infinite loops and allows human judgment for complex failures.

Structure

Section titled “Structure”
[action] → [verify] → failure → [check-retries] → retries<max → [retry]
                                               → retries>=max → [escalate-to-user]

Implementation

Section titled “Implementation”

Retry Limit Check

Section titled “Retry Limit Check”
{
  "type": "condition",
  "id": "check-retry-limit",
  "condition": {
    "operator": "lt",
    "left": { "contextPath": "current_iteration" },
    "right": 3
  },
  "connections": {
    "true": "fix-and-retry",
    "false": "escalate-to-user"
  }
}

Escalation Node

Section titled “Escalation Node”
{
  "type": "agent-directive",
  "id": "escalate-to-user",
  "directive": "Automated resolution failed after {{current_iteration}} attempts.\n\nProblem: {{last_error}}\nAttempted fixes: {{attempted_fixes}}\n\nAsk user how to proceed:\n- Provide manual fix instructions?\n- Skip this step?\n- Abort workflow?",
  "inputSchema": {
    "type": "object",
    "properties": {
      "user_decision": { "type": "string", "enum": ["fix", "skip", "abort"] },
      "user_instructions": { "type": "string" }
    },
    "required": ["user_decision"]
  },
  "connections": { "success": "route-user-decision" }
}

Route User Decision

Section titled “Route User Decision”
{
  "type": "condition",
  "id": "check-abort",
  "condition": {
    "operator": "eq",
    "left": { "contextPath": "user_decision" },
    "right": "abort"
  },
  "connections": {
    "true": "workflow-aborted",
    "false": "check-skip"
  }
}
{
  "type": "condition",
  "id": "check-skip",
  "condition": {
    "operator": "eq",
    "left": { "contextPath": "user_decision" },
    "right": "skip"
  },
  "connections": {
    "true": "proceed-to-next",
    "false": "apply-user-fix"
  }
}

Collecting Error Context

Section titled “Collecting Error Context”

Track errors during retries:

{
  "id": "handle-error",
  "directive": "Record error details for escalation context.\n\nCurrent iteration: {{current_iteration}}\nError encountered: [describe error]",
  "inputSchema": {
    "properties": {
      "last_error": { "type": "string" },
      "attempted_fix": { "type": "string" }
    },
    "required": ["last_error"]
  }
}

Graceful Abort

Section titled “Graceful Abort”
{
  "type": "agent-directive",
  "id": "workflow-aborted",
  "directive": "User chose to abort workflow.\n\nCleanup tasks:\n- Save partial progress\n- Document what was completed\n- Note why abort was necessary",
  "inputSchema": {
    "properties": {
      "cleanup_completed": { "type": "boolean" },
      "progress_summary": { "type": "string" }
    },
    "required": ["cleanup_completed"]
  },
  "connections": { "success": "end-aborted" }
}

Escalation Levels

Section titled “Escalation Levels”

For complex workflows, consider multiple escalation levels:

  1. Auto-retry: First 3 attempts
  2. Agent analysis: Deeper investigation
  3. User notification: Inform but continue
  4. User intervention: Require decision
  5. Full abort: Stop workflow

Real Example

Section titled “Real Example”

From development-flow.json:

{
  "id": "collect-user-feedback",
  "directive": "Verification failed {{current_iteration}} times.\n\nAsk user:\n- Provide guidance for resolution?\n- Skip this step?\n- Modify the plan?\n\nSummarize the problem and what has been attempted.",
  "inputSchema": {
    "properties": {
      "user_guidance": { "type": "string" },
      "decision": { "type": "string", "enum": ["continue", "skip", "modify"] }
    },
    "required": ["decision"]
  }
}
Section titled “Related Patterns”