Saga Orchestration Failure Recovery Prompt

Use this prompt when you are designing or reviewing a saga-based distributed transaction and need a rigorous failure mode analysis of your compensating transactions. The prompt is built for architects and backend engineers who have already chosen the saga pattern and are now defining the rollback logic. It is not a tutorial on sagas; it assumes you understand orchestration, compensation, and eventual consistency. The primary job-to-be-done is to surface incomplete compensation paths, ordering constraints that break during partial failures, and irreversible side effects that cannot be rolled back by code alone.

This prompt requires specific inputs to be useful. You must provide a description of the saga steps in order, the compensating action for each step, and any known constraints such as external payment gateways, inventory systems, or third-party APIs that lack undo capabilities. Without these details, the model will produce generic advice that fails to identify the real risks in your system. The prompt works best when you also supply a concrete failure scenario—such as 'step 3 succeeds but step 4 fails after the payment is captured'—so the analysis can trace the exact compensation path and flag gaps.

Do not use this prompt for simple request-response workflows, single-service transactions, or systems that rely on ACID database transactions within a single resource manager. It is also not a substitute for chaos engineering or production testing; the output is a design-time analysis that identifies theoretical failure modes, not runtime behavior. If your system handles financial reconciliation, healthcare data, or other regulated domains, treat the prompt's output as a starting point for a formal failure mode and effects analysis (FMEA) that includes human review and evidence grounding. After running the prompt, take the identified gaps and design compensating actions or manual intervention workflows before writing implementation code.

This section provides the core prompt template for evaluating saga orchestration failure recovery. The template is designed to be copied directly into your AI harness, with square-bracket placeholders that you replace with your specific saga definition, compensation catalog, and risk tolerance. The prompt forces the model to reason about compensation ordering constraints, irreversible side effects, and partial failure states—not just happy-path rollback. Use this template when you have a defined saga with explicit compensating transactions and need a structured failure mode analysis before implementation begins.

textCopy
You are a distributed systems architect specializing in saga orchestration patterns and compensating transaction design. Your task is to analyze the failure recovery strategy for a saga orchestration and identify gaps in compensation completeness, ordering constraints, and partial failure handling.

## SAGA DEFINITION
[SAGA_NAME]: [SAGA_DESCRIPTION]

[SAGA_STEPS]
- Step [STEP_ID]: [STEP_DESCRIPTION] | Compensation: [COMPENSATION_DESCRIPTION] | Reversible: [YES/NO/PARTIAL]

## CONTEXT
[CONTEXT]
Include any relevant context about the system, such as:
- Service boundaries and ownership
- Transactional vs. non-transactional resources
- External system dependencies
- Business impact of partial failures

## CONSTRAINTS
[CONSTRAINTS]
Specify any constraints that affect recovery design, such as:
- Maximum acceptable recovery time
- Data consistency requirements (eventual, strong, etc.)
- Regulatory or compliance requirements
- Irreversible operations that cannot be compensated

## OUTPUT SCHEMA
Return a JSON object with the following structure:
{
  "analysis": {
    "compensation_completeness": {
      "status": "COMPLETE|INCOMPLETE|PARTIAL",
      "missing_compensations": [
        {
          "step_id": "string",
          "gap_description": "string",
          "risk_level": "HIGH|MEDIUM|LOW",
          "suggested_compensation": "string"
        }
      ],
      "coverage_percentage": number
    },
    "ordering_constraints": [
      {
        "constraint_type": "SEQUENTIAL|PARALLEL|CONDITIONAL",
        "affected_steps": ["string"],
        "description": "string",
        "violation_risk": "string"
      }
    ],
    "irreversible_side_effects": [
      {
        "step_id": "string",
        "effect_description": "string",
        "mitigation_strategy": "string",
        "acceptance_required": true
      }
    ],
    "partial_failure_scenarios": [
      {
        "scenario_id": "string",
        "failing_step": "string",
        "completed_steps": ["string"],
        "in_flight_steps": ["string"],
        "recovery_path": "string",
        "data_inconsistency_risk": "HIGH|MEDIUM|LOW",
        "recommended_action": "string"
      }
    ]
  },
  "test_scenarios": [
    {
      "scenario_name": "string",
      "failure_injection_point": "string",
      "expected_behavior": "string",
      "compensation_chain": ["string"],
      "verification_criteria": ["string"]
    }
  ],
  "recommendations": [
    {
      "priority": "CRITICAL|HIGH|MEDIUM|LOW",
      "category": "COMPENSATION|ORDERING|IDEMPOTENCY|MONITORING|TESTING",
      "description": "string",
      "implementation_effort": "LOW|MEDIUM|HIGH"
    }
  ],
  "risk_summary": {
    "overall_risk_level": "HIGH|MEDIUM|LOW",
    "unresolved_risks": ["string"],
    "requires_human_review": true
  }
}

## ANALYSIS REQUIREMENTS
1. For each saga step, verify that a compensating transaction exists and is complete.
2. Identify ordering dependencies between compensations—some compensations must run in reverse order, others can run in parallel.
3. Flag any irreversible side effects (e.g., sent emails, external API calls with no undo, physical actions) and recommend mitigation.
4. Enumerate partial failure scenarios where some steps succeeded and others are in-flight when failure occurs.
5. Generate test scenarios that specifically target compensation failures, not just saga step failures.
6. If any compensation itself can fail, recommend idempotency guards and retry strategies.
7. For high-risk scenarios, recommend human approval gates before compensation execution.

## RISK LEVEL
[RISK_LEVEL]
Specify the risk tolerance for this analysis: LOW, MEDIUM, HIGH, or CRITICAL. This affects the depth of scenario enumeration and the threshold for flagging issues.

After copying the template, replace each square-bracket placeholder with your specific saga details. The [SAGA_STEPS] section is the most critical—each step must include its compensation definition and reversibility flag. For steps marked PARTIAL or NO, the model will generate specific mitigation strategies rather than assuming full rollback is possible. The [RISK_LEVEL] parameter controls analysis depth: CRITICAL risk triggers exhaustive scenario enumeration including double-fault conditions where a compensation itself fails. Wire the output schema into your validation pipeline to ensure the JSON structure is parseable before surfacing results to your architecture review process.

This prompt is designed to operate as a synchronous design review step within a broader architecture governance workflow. It should be called after a saga orchestration design document is drafted but before the design is approved for implementation. The prompt expects a structured input containing the saga definition, participant services, and compensation definitions. Wire it into your CI/CD pipeline, architecture review board tooling, or internal developer portal as a gated check that runs when a new saga design or a modification to an existing saga is proposed.

Integration pattern: POST the assembled prompt to your model API (GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro are recommended for this structured reasoning task). The request must include response_format: { type: "json_object" } or equivalent structured output mode. On the client side, validate the response against a JSON schema that enforces the expected output shape: a failure_modes array, each with failure_scenario, compensation_gaps, ordering_risks, irreversible_side_effects, and severity fields. Reject and retry up to two times if the output fails schema validation or if the severity field contains values outside the expected enum (CRITICAL, HIGH, MEDIUM, LOW). Log every validation failure for prompt drift analysis.

Human review gate: For any saga design where the prompt returns one or more CRITICAL severity findings, the workflow must block automatic approval and route the output to a designated architecture reviewer. The review interface should display the original saga design, the model's failure mode analysis, and a structured approval form. The reviewer must explicitly acknowledge or override each critical finding before the design can proceed. For HIGH severity findings, consider a softer gate: allow the design to proceed with a mandatory follow-up task to address the finding within a defined sprint window. Observability: Attach trace metadata to each prompt call—saga name, version, requesting team, and model used—so you can track which designs triggered the most findings and whether prompt effectiveness drifts across model versions.