Saga Orchestration Design Evaluation Prompt

Use this prompt when you are an engineer or architect reviewing a long-running transaction design that spans multiple services, databases, or bounded contexts. The job-to-be-done is a structured critique of a saga's orchestration logic, focusing on compensation, idempotency, timeout handling, and failure modes. You should have a concrete saga design in front of you—whether as a sequence diagram, a written specification, or a code skeleton—and you need a systematic evaluation before the design reaches implementation or code review. This prompt is not for greenfield saga design from scratch; it assumes a design exists and needs a rigorous review.

The ideal user is a backend engineer, platform engineer, or architect who understands distributed transactions and has already sketched out the saga steps, participant services, and compensating actions. Required context includes the saga's trigger, the sequence of local transactions, the compensation path for each step, timeout policies, and any retry or idempotency mechanisms. If you are missing these details, the prompt will produce a low-confidence critique full of assumptions. Do not use this prompt for simple request-response workflows, single-service transactions, or synchronous API chains that lack explicit compensation logic—those do not constitute sagas and will produce irrelevant output.

This prompt is also inappropriate when you need a production-grade formal verification of a saga's correctness. The model can identify missing compensation steps, flag timeout gaps, and surface idempotency risks, but it cannot prove liveness or safety properties. For high-risk financial, healthcare, or compliance-critical sagas, treat the model's output as a design review aid, not a replacement for peer review, formal modeling, or failure injection testing. The output should feed into your team's architecture decision process, not serve as the final sign-off.

This prompt template is designed to evaluate a saga orchestration design by systematically analyzing its compensation logic, idempotency guarantees, timeout handling, and failure modes. The template uses square-bracket placeholders so you can inject your own saga specification, domain constraints, and output format requirements without rewriting the core evaluation logic. Before using this prompt, gather your saga definition—including the sequence of steps, their compensating actions, and any state machine or orchestrator logic—so the model has enough detail to produce a meaningful critique.

textCopy
You are a senior backend architect specializing in distributed systems and long-running transaction patterns. Your task is to evaluate a saga orchestration design and produce a structured critique.

## INPUT
[SAGA_DEFINITION]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT SCHEMA
You must return a valid JSON object with the following structure:
{
  "overall_assessment": "PASS | FAIL | NEEDS_REVIEW",
  "summary": "One-paragraph summary of the design's strengths and weaknesses.",
  "compensation_review": {
    "missing_compensations": ["step_name or description of missing rollback"],
    "compensation_order_issues": ["description of ordering problems"],
    "partial_failure_handling": "Assessment of how the design handles partial completion during rollback."
  },
  "idempotency_review": {
    "idempotent_steps": ["steps that are idempotent"],
    "non_idempotent_steps": ["steps lacking idempotency guarantees"],
    "duplicate_execution_risks": ["scenarios where duplicate execution could cause harm"]
  },
  "timeout_and_retry_review": {
    "timeout_configuration": "Assessment of timeout values per step and overall saga.",
    "retry_policy": "Assessment of retry strategy, backoff, and max attempts.",
    "stuck_saga_risks": ["scenarios where the saga could hang indefinitely"]
  },
  "failure_mode_analysis": [
    {
      "failure_scenario": "Description of a specific failure.",
      "impact": "What happens in the current design.",
      "recommendation": "How to mitigate or handle this failure."
    }
  ],
  "missing_concerns": ["Any cross-cutting concerns not addressed in the design."],
  "recommendations": ["Actionable, prioritized recommendations for improvement."]
}

## EVALUATION CRITERIA
1. Every forward step must have a defined compensating action or a documented reason why compensation is unnecessary.
2. Every step must be idempotent or include a deduplication mechanism.
3. Timeouts must be defined per step and for the overall saga execution.
4. The design must specify what happens when a compensation step itself fails.
5. The saga must have a terminal state for every possible execution path.

## INSTRUCTIONS
- Be specific. Reference step names and sequences from the provided saga definition.
- Flag missing compensations explicitly, even if the design implies they exist.
- If the saga uses choreography instead of orchestration, note the additional risks around distributed state tracking.
- If the design is incomplete, set overall_assessment to NEEDS_REVIEW and explain what information is missing.
- Do not invent steps or compensations that are not described in the input.

To adapt this template, replace [SAGA_DEFINITION] with your full saga specification—including step names, their order, compensating actions, timeout values, retry policies, and the orchestrator or choreography mechanism. Replace [CONSTRAINTS] with any domain-specific rules such as "all steps must complete within 30 seconds" or "compensation steps must not call external payment gateways." If your team uses a specific output format, adjust the OUTPUT SCHEMA block to match your internal review template. For high-risk financial or healthcare sagas, add a [RISK_LEVEL] placeholder and instruct the model to escalate findings that could cause data inconsistency or financial loss. After generating the critique, always have a senior engineer review the findings before accepting or rejecting the recommendations—the model can miss subtle interaction effects between timeout configurations and retry policies that only manifest under production load.

This prompt is designed to run as part of a pre-implementation design review gate, not as a runtime decision engine. Wire it into a pull request workflow, an architecture review checklist, or a design document pipeline where engineers submit saga specifications before coding begins. The prompt expects a structured saga definition as input—typically a JSON or YAML document describing steps, compensation actions, timeouts, retry policies, and participant services. If your team maintains saga definitions in a registry or design tool, extract the relevant specification and pass it as [SAGA_SPECIFICATION]. The [CONSTRAINTS] placeholder should carry your organization's specific policies: maximum saga duration, required idempotency guarantees, approved compensation patterns, and any regulatory requirements around transaction integrity.

Model choice matters here. Use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or Gemini 1.5 Pro) because the evaluation requires multi-step causal reasoning about failure propagation and compensation ordering. Avoid smaller or faster models that may miss subtle failure mode interactions. Validation layer: Parse the model's JSON output immediately and validate that all required fields are present (saga_id, findings, severity, recommendation, missing_compensations, idempotency_gaps, timeout_risks). If validation fails, retry once with the validation errors appended to the prompt as feedback. If the second attempt also fails, flag the review for human triage—do not silently accept incomplete evaluations. Logging: Capture the full prompt, model response, validation result, and any retry attempts in your design review audit trail. This is critical for governance if a saga defect reaches production.

Human approval gate: All findings with severity: critical or severity: high should block automated approval and require a human architect to acknowledge or override. Implement this as a status check in your review system—the prompt output should set a requires_human_review boolean that your workflow engine respects. For lower-severity findings, you can auto-approve but still surface them in the design document as review comments. Tool integration: If your saga definitions reference external service contracts, consider augmenting this prompt with a retrieval step that pulls the latest API specs or SLA documents for those services before evaluation. This grounds the timeout and idempotency checks in actual service guarantees rather than assumptions. What to avoid: Do not use this prompt as a runtime saga executor or decision maker. It evaluates designs, not live transactions. Do not skip the human review gate for critical findings—saga failures in production can cause data corruption that is expensive to repair.