Retry Budget for Non-Idempotent Action Escalation Prompt

This prompt is designed for distributed-systems engineers and platform architects who need to embed a retry policy directly into an AI agent's decision loop. Its primary job is to classify an action as idempotent or non-idempotent, and if the latter, to minimize retries and escalate immediately when a retry could cause a duplicate side effect—such as a double charge, a duplicate database write, or a redundant external API call. The ideal user is someone integrating an LLM into a production harness where the model is allowed to trigger real-world actions, not just generate text. You need this prompt when your agent's tool-use layer includes POST, PUT, DELETE, or any state-mutating operation where replaying the request without explicit idempotency keys is unsafe.

You should not use this prompt if all actions in the current workflow are read-only or naturally idempotent (e.g., GET requests, idempotent PUT operations with client-supplied keys). In those cases, a standard retry budget with exponential backoff is sufficient. This prompt is also unnecessary if your application layer already enforces strict idempotency via unique request identifiers and the model is merely a text generator with no side-effect authority. The prompt becomes critical when the model itself decides whether to retry a failed action, and that decision must be constrained by the risk of duplication. Required context includes: the original action description, the error or failure signal received, the current retry count, the maximum retry budget, and a clear definition of what constitutes a non-idempotent side effect in your domain.

Before deploying this prompt, ensure your harness can enforce the escalation decision. The prompt produces a structured policy output—either retry with a modified action or escalate with a packaged context for human review. If the prompt escalates, your system must stop retrying and route the payload to a human operator or a dead-letter queue. Do not allow the model to override the escalation decision in a subsequent turn. The next step after reading this section is to copy the prompt template, adapt the [IDEMPOTENCY_RULES] and [ESCALATION_TARGET] placeholders to your system's specific side-effect taxonomy and routing logic, and then wire it into your agent's error-recovery loop with the validation checks described in the implementation harness.

This prompt template is designed to be injected into a system instruction or used as a structured task for a model acting as a reliability guard. Its job is to analyze a proposed action, determine if a retry could cause a duplicate side effect (e.g., double payment, duplicate resource creation), and output a strict retry policy. For non-idempotent actions, the policy must enforce a retry budget of zero or one, demanding immediate escalation to a human or a dead-letter queue instead of a standard retry loop.

codeCopy
You are a reliability policy engine. Analyze the following action and context to determine its idempotency classification and generate a safe retry policy.

## Inputs
- **Action Description:** [ACTION_DESCRIPTION]
- **Target System/API:** [TARGET_SYSTEM]
- **Request Payload:** [REQUEST_PAYLOAD]
- **Current Retry Count:** [CURRENT_RETRY_COUNT]
- **Failure Reason:** [FAILURE_REASON]

## Classification Rules
1.  **Non-Idempotent:** The action creates a new resource, triggers a financial transaction, sends a notification, or mutates state without a unique idempotency key. Retries risk duplicate side effects.
2.  **Idempotent:** The action is a read, an update with a known state, a delete, or a create with a client-supplied unique key that the server respects.
3.  **Uncertain:** The action's idempotency depends on external state not visible in the payload. Treat as Non-Idempotent.

## Output Schema
Return a JSON object with the following structure:
{
  "classification": "non_idempotent" | "idempotent" | "uncertain",
  "reasoning": "Brief justification for the classification.",
  "retry_policy": {
    "max_retries": 0,
    "action_on_budget_exhaustion": "escalate_to_human" | "dead_letter_queue" | "discard",
    "escalation_payload": {
      "failure_summary": "Concise summary of the failure and why retrying is unsafe.",
      "original_action": "[ACTION_DESCRIPTION]",
      "failure_reason": "[FAILURE_REASON]",
      "recommended_human_action": "Clear next step for a human operator."
    }
  }
}

## Constraints
- If classification is `non_idempotent` or `uncertain`, `max_retries` MUST be 0.
- The `escalation_payload` must be populated only if `max_retries` is 0.
- Do not suggest retrying with a generated idempotency key unless the target system's API documentation explicitly supports it.

To adapt this template, replace the square-bracket placeholders with data from your application's execution context. The [ACTION_DESCRIPTION] should be a high-level summary of what the agent or service is trying to do. The [REQUEST_PAYLOAD] should be the exact data sent to the external system, which is critical for the model to inspect for idempotency keys. Wire this prompt into your retry harness so that it is called before any retry logic executes. If the returned max_retries is 0, bypass your standard exponential backoff and directly execute the escalation path defined in the escalation_payload.

This prompt is designed to sit inside a retry harness that intercepts a failed action, classifies its idempotency risk, and decides whether to retry or escalate. The harness must provide the prompt with the original action description, the error or failure context, and any relevant state that indicates whether a duplicate execution would cause harm. The prompt is not a standalone decision engine—it is a structured reasoning step that produces a classification and a recommended action, which the harness then enforces.

Wire the prompt into your application by wrapping the non-idempotent action execution in a try/catch or error-handling middleware. On failure, call the prompt with [ACTION_DESCRIPTION], [FAILURE_CONTEXT], and [IDEMPOTENCY_CLUES] populated from the action's metadata and the error trace. Parse the model's output against a strict schema that requires idempotency_classification (one of idempotent, non_idempotent, uncertain), retry_decision (one of retry, escalate, human_review), and rationale. If the classification is non_idempotent or uncertain, your harness must immediately escalate—do not retry. If idempotent, you may retry up to the remaining retry budget. Log every decision with the full prompt input, model output, and harness action for auditability.

Add a pre-flight check before calling the prompt: if the action is tagged as non-idempotent in your system's action registry (e.g., payment capture, email send, stateful write), bypass the prompt entirely and escalate directly. The prompt is a safety net for actions where idempotency is ambiguous or context-dependent, not a replacement for explicit action metadata. For high-risk domains like financial transactions or healthcare operations, require human approval on any escalate or human_review decision. Validate the model's output schema before acting on it—if parsing fails, treat it as an uncertain classification and escalate. Never default to retry on parse failure.