Saga Orchestration vs Choreography Decision Prompt

This prompt is for architects and backend engineers who must choose a coordination strategy for a cross-service business process that spans multiple transactional boundaries. The job-to-be-done is producing a structured, defensible comparison of orchestration and choreography for a specific process, not a generic pattern recommendation. Use this prompt when you have a concrete business flow with known services, data stores, and failure modes, and you need a decision document that captures trade-offs across complexity, observability, coupling, and team autonomy before implementation begins.

The ideal user has already mapped the process steps, identified participating services, and understands the consistency requirements for each step. Required context includes the process name, a sequenced list of steps with owning services, compensation or rollback requirements, latency expectations, and any existing infrastructure constraints such as message broker availability or workflow engine adoption. Do not use this prompt for greenfield pattern selection without a concrete process, for processes that fit within a single database transaction, or when the team has already committed to a specific coordination infrastructure and only needs implementation guidance. The prompt is also inappropriate for processes where the primary concern is data consistency under high contention, which requires a transaction boundary analysis prompt instead.

The output is a structured comparison with a recommended pattern and explicit boundary conditions that would trigger reconsideration. Wire this into an architecture review workflow where the decision is documented as an ADR or design memo. For high-risk financial or compliance processes, require human review of the recommendation and validate that compensation steps are complete and testable. The prompt assumes the reader can evaluate the trade-offs independently; it does not replace engineering judgment about team maturity, operational capability, or existing infrastructure investment. After using this prompt, the next step is to document the chosen pattern with the specific saga definition, compensation logic, and observability hooks required for production.

The following prompt template is designed to be copied directly into your AI harness. It forces a structured, side-by-side comparison of the two primary saga implementation patterns—orchestration and choreography—for a single, concrete business process. The template uses square-bracket placeholders for all variable inputs, ensuring you can adapt it to any cross-service transaction without leaking implementation details into the prompt. Before using it, gather a clear description of the business process, the services involved, any compensating actions, and the non-functional requirements that matter most to your team, such as observability requirements, team autonomy preferences, or latency budgets.

textCopy
You are a senior distributed systems architect evaluating saga implementation patterns for a specific business process. Your task is to produce a structured, evidence-based comparison between the Orchestration and Choreography patterns, culminating in a clear recommendation with explicit boundary conditions.

## INPUT
[BUSINESS_PROCESS_DESCRIPTION]

## SERVICES INVOLVED
[SERVICE_LIST_WITH_RESPONSIBILITIES]

## COMPENSATING ACTIONS
[COMPENSATING_ACTIONS_PER_STEP]

## CONSTRAINTS
[CONSTRAINTS]

## OUTPUT SCHEMA
You must respond with a valid JSON object conforming to this exact structure:
{
  "process_summary": "A one-paragraph summary of the business process and its transactional requirements.",
  "orchestration_assessment": {
    "description": "How an orchestration-based saga would work for this process, including the orchestrator's responsibilities.",
    "strengths": ["List of specific strengths for this process."],
    "weaknesses": ["List of specific weaknesses for this process."],
    "complexity_score": "A score from 1 (trivial) to 10 (extremely complex) for implementing this pattern.",
    "observability_score": "A score from 1 (opaque) to 10 (fully observable) for this pattern.",
    "coupling_score": "A score from 1 (loosely coupled) to 10 (tightly coupled) for this pattern.",
    "team_autonomy_score": "A score from 1 (low autonomy) to 10 (high autonomy) for this pattern."
  },
  "choreography_assessment": {
    "description": "How a choreography-based saga would work for this process, including event flows.",
    "strengths": ["List of specific strengths for this process."],
    "weaknesses": ["List of specific weaknesses for this process."],
    "complexity_score": "A score from 1 to 10.",
    "observability_score": "A score from 1 to 10.",
    "coupling_score": "A score from 1 to 10.",
    "team_autonomy_score": "A score from 1 to 10."
  },
  "recommendation": {
    "chosen_pattern": "Orchestration" | "Choreography" | "Hybrid",
    "rationale": "A paragraph explaining the primary drivers for this recommendation, referencing the scores above.",
    "boundary_conditions": "Specific conditions under which this recommendation should be re-evaluated (e.g., if the number of services exceeds X, if a central team is formed).",
    "hybrid_description": "If Hybrid is chosen, describe which parts are orchestrated and which are choreographed. Otherwise, set to null."
  },
  "risk_register": [
    {
      "risk": "Description of a specific failure mode for the chosen pattern.",
      "severity": "Low" | "Medium" | "High",
      "mitigation": "A concrete mitigation strategy."
    }
  ]
}

## INSTRUCTIONS
1. Base your analysis strictly on the provided business process, services, and constraints. Do not invent additional requirements.
2. For each score, provide a brief justification in your reasoning before outputting the JSON. Do not include the justification in the JSON output itself.
3. If the constraints explicitly favor one pattern (e.g., a requirement for a central audit log), weight your recommendation accordingly.
4. The risk register must include at least two risks specific to the chosen pattern.
5. If the process has fewer than 3 steps, note that in the process_summary and adjust complexity scores downward.

To adapt this template, replace each bracketed placeholder with concrete details from your design session. The [BUSINESS_PROCESS_DESCRIPTION] should be a narrative of the end-to-end flow, including the happy path and known failure modes. The [SERVICE_LIST_WITH_RESPONSIBILITIES] must name each service and its role in the transaction, as ambiguity here leads to vague assessments. The [COMPENSATING_ACTIONS_PER_STEP] field is critical—map each step to its semantic undo operation. If a step has no compensating action, state that explicitly. The [CONSTRAINTS] field is where you inject non-functional requirements like latency budgets, team topology, regulatory audit needs, or existing technology standards. This prompt is designed for a single-turn generation; if you need to iterate, re-run it with refined constraints rather than asking the model to revise its previous output.

After copying the template, validate that your placeholders contain enough detail to produce a non-obvious recommendation. A vague input like "Process an order" will yield a generic, low-value response. A detailed input describing a five-step order process with payment capture, inventory reservation, shipping dispatch, and notification—each with specific compensating actions and a constraint for a centralized customer support view—will produce a nuanced, actionable comparison. For high-stakes architectural decisions, always review the output with the team and treat the model's recommendation as a structured starting point for discussion, not a final verdict.

This prompt is designed to be embedded in an architecture review pipeline, not used as a one-off chat. The primary integration point is a structured input form or API payload that collects the business process description, participating services, consistency requirements, and team topology context before the prompt is assembled. The prompt expects these inputs as structured fields that map to the [BUSINESS_PROCESS], [SERVICE_INVENTORY], [CONSISTENCY_REQUIREMENTS], and [TEAM_TOPOLOGY] placeholders. In production, these fields should be sourced from an architecture registry, service catalog, or incident postmortem database rather than free-text entry, ensuring the model reasons over accurate, current system data rather than stale or incomplete descriptions.

The implementation harness should enforce a two-stage validation pipeline. First, validate the input payload against a schema that requires at minimum: a named business process with step-by-step flow, a list of participating services with their data ownership boundaries, explicit consistency requirements per step (atomic, eventually consistent, or best-effort), and team ownership mappings. Reject incomplete inputs before the model call. Second, validate the model's output against an expected schema that includes: a decision field (orchestration, choreography, or hybrid), a scored comparison matrix across the required criteria dimensions, explicit boundary conditions where the recommendation changes, and a risk register. If the output fails schema validation, retry with a repair prompt that includes the validation errors. After three failed repair attempts, escalate to a human architect for manual review.

For model selection, use a model with strong structured reasoning capabilities and long-context handling, as the prompt requires simultaneous evaluation of multiple services, consistency boundaries, and team structures. GPT-4o or Claude 3.5 Sonnet are appropriate defaults. Set temperature to 0.1–0.2 to reduce variance in the comparison matrix scoring. Enable JSON mode or structured output mode if the model supports it, providing the output schema as a tool definition or response format parameter. For logging and observability, capture the full prompt, input payload, model response, validation results, and any repair attempts in an architecture decision log. Tag each run with the business process identifier and a timestamp so teams can trace how the saga pattern recommendation evolved as the system changed.

This prompt is high-risk because the chosen saga pattern directly affects data consistency, operational complexity, and team coordination for months or years. The output must never be applied automatically. Always route the final recommendation through a human approval gate where a senior architect or technical lead reviews the comparison matrix, boundary conditions, and risk register before updating any architecture decision record. Store the approved output alongside the ADR with a link back to the prompt run that generated it. If the prompt recommends a hybrid pattern, require two independent reviewers to confirm the boundary conditions are clear and enforceable in practice.

For tool integration, wire the prompt into your existing architecture toolchain. If your team uses an ADR repository (e.g., markdown files in version control, or a tool like Structurizr or LeanIX), the harness should generate a draft ADR from the validated output and open a pull request or review ticket. If you maintain a service catalog, update the service metadata to reflect the chosen saga pattern and any new coordination dependencies. Do not let the prompt output sit in a chat window—the value comes from routing the structured decision into the systems that govern implementation and operations.