Saga Orchestration Flow Design Prompt

This prompt is for architects and backend engineers who are designing a distributed transaction that spans multiple services and must maintain data consistency without relying on traditional ACID transactions. The job-to-be-done is a structured design review of a saga orchestration flow before a single line of code is written. You should use this prompt when you have a concrete business process—such as order fulfillment, payment processing with inventory reservation, or multi-service account provisioning—that requires a sequence of local transactions with compensating actions for rollback. The ideal user has already mapped the high-level steps and is now ready to pressure-test the flow for missing compensation logic, orphaned state, timeout handling, and failure recovery gaps.

Do not use this prompt for simple request-response workflows, single-service operations, or processes where eventual consistency is acceptable without explicit rollback. It is also not a replacement for a choreography-based event design review; if your services communicate through broadcasted events without a central coordinator, use the Choreography vs Orchestration Decision Prompt instead. This prompt assumes an orchestrator pattern where one service directs the saga. You will need to provide the sequence of steps, the compensation action for each step, timeout thresholds, and any idempotency or retry policies already in place. The prompt works best when you supply a concrete flow diagram or step list rather than an abstract description.

After running this prompt, you will receive a structured review that identifies missing compensation steps, orphaned state risks, timeout handling gaps, and failure state recovery weaknesses. The output is designed to be actionable: each finding includes a severity, a rationale, and a suggested remediation. Before you integrate the output into your design document, validate that every identified gap maps to a real step in your flow and that no false positives have been introduced by ambiguous step naming. For high-risk financial or compliance workflows, always have a second architect review the findings before finalizing the saga design.

This prompt template is the core engine of the playbook. It instructs the model to act as a distributed systems architect and produce a rigorous review of a proposed saga orchestration flow. The template uses square-bracket placeholders for all variable inputs, making it safe to inject into a production system without accidental tokenization issues. You should fill these placeholders with your specific saga definition, business context, and output requirements before sending the prompt to the model.

textCopy
You are a principal distributed systems architect reviewing a saga orchestration design for a microservices environment. Your task is to produce a structured design review that identifies risks, gaps, and failure modes before implementation.

## SAGA DEFINITION
[SAGA_NAME]: [SAGA_DESCRIPTION]

[SAGA_STEPS]

## BUSINESS CONTEXT
[CONSISTENCY_REQUIREMENTS]
[TIMEOUT_CONSTRAINTS]
[CRITICALITY_LEVEL]

## REVIEW INSTRUCTIONS
Analyze the saga definition and produce a review with the following sections. Be specific and critical. If a section has no findings, state that explicitly.

1.  **Step Sequencing Analysis**: Evaluate the order of steps. Are there any steps that should be reordered to reduce the window of inconsistency? Identify any implicit assumptions about synchronous vs. asynchronous execution.
2.  **Compensation Logic Audit**: For every step that has a side effect, verify that a corresponding compensation step is defined. Flag any missing compensations. Assess the idempotency of each compensation step.
3.  **Failure State and Timeout Handling**: Analyze the defined behavior for step timeouts, service unavailability, and permanent failures. Identify scenarios that could lead to orphaned state or incomplete transactions. Evaluate the retry strategy for each step.
4.  **Orphaned State and Recovery**: Identify any failure scenarios where the saga could terminate but leave resources in an inconsistent state (e.g., a payment captured but an order not created). Propose a recovery mechanism or manual intervention point.
5.  **Observability and Operational Readiness**: Assess the design's traceability. Are correlation IDs propagated? Are there clear points to log the saga's progress, state transitions, and compensation actions? Identify observability gaps that would make debugging a production failure difficult.

## OUTPUT FORMAT
Return your review as a JSON object with the following schema:
{
  "saga_name": "string",
  "overall_risk_assessment": "low" | "medium" | "high" | "critical",
  "step_sequencing_analysis": {
    "findings": [{"severity": "string", "description": "string", "recommendation": "string"}],
    "overall_assessment": "string"
  },
  "compensation_logic_audit": {
    "missing_compensations": [{"step": "string", "risk": "string"}],
    "idempotency_concerns": [{"step": "string", "issue": "string"}],
    "overall_assessment": "string"
  },
  "failure_state_analysis": {
    "orphaned_state_scenarios": [{"scenario": "string", "impact": "string", "recovery_suggestion": "string"}],
    "timeout_handling_gaps": ["string"],
    "overall_assessment": "string"
  },
  "observability_readiness": {
    "gaps": ["string"],
    "recommended_logging_points": ["string"],
    "overall_assessment": "string"
  }
}

To adapt this template, replace the placeholders with your concrete design details. For [SAGA_STEPS], provide a structured list of steps, each with its action and its compensating action. For example: Step 1: ReserveInventory() / Compensation: ReleaseInventory(). The [CRITICALITY_LEVEL] field should be a value like low, medium, high, or critical to calibrate the review's intensity. After running the prompt, you must validate the output JSON against the provided schema. Any deviation, such as a missing key or an invalid enum value, should trigger a retry or a repair prompt. For high-criticality sagas, the output of this review should be treated as a draft requiring human architect approval before being used to generate implementation code.

This prompt is designed to be called programmatically as part of an architecture review pipeline, not as a one-off chat interaction. The core integration pattern is: collect the saga specification (steps, compensations, timeouts, state), assemble the prompt with the template placeholders filled, call a capable reasoning model, validate the structured output, and surface findings to a human reviewer or design review system. The prompt expects a detailed saga design as input, so your application must either accept a structured specification (YAML, JSON, or a design document) or guide the user to provide one before invocation.

Validation and retry logic is critical because the output schema includes enumerated severity levels (BLOCKER, WARNING, INFO) and structured finding objects. Implement a JSON schema validator on the model response. If the output fails schema validation, retry once with a repair prompt that includes the validation error and the original input. If the second attempt also fails, log the failure and escalate to a human reviewer with the raw output attached. For high-risk sagas (e.g., payment processing, inventory allocation), require explicit human approval on all BLOCKER findings before the design is accepted. Log every invocation with the input hash, model version, output, and reviewer decision for auditability.

Model selection matters: use a model with strong reasoning capabilities (GPT-4o, Claude 3.5 Sonnet, or equivalent) because the task requires multi-step causal reasoning about failure propagation and compensation chains. Avoid smaller or faster models that may miss subtle state corruption scenarios. If you are reviewing many sagas in a CI pipeline, consider batching non-critical reviews during off-peak hours and reserving synchronous execution for high-severity design changes. Tool use is not required for this prompt, but you may extend the harness to fetch related ADRs, incident reports, or existing saga definitions from a knowledge base to ground the review in organizational context. If you do, inject that context into the [CONTEXT] placeholder and cite sources in the output.

Next steps: After integrating this prompt, build a dashboard that tracks finding resolution over time. Sagas with repeated BLOCKER findings across revisions indicate a design process problem, not just a single bad design. Avoid the temptation to auto-apply fixes based on model suggestions—compensation logic changes must be reviewed by an engineer who understands the business invariants. The prompt identifies gaps; humans decide how to close them.