Orchestrate Distributed Transactions with Sagas

This skill provides patterns and working templates for managing distributed transactions and long-running business processes via the saga pattern. It distinguishes two saga types - choreography (services react to each other's events directly) and orchestration (a central orchestrator coordinates each service) - and defines the saga execution states: Started, Pending, Compensating, Completed, and Failed.

It provides four code templates. A base SagaOrchestrator class tracks a Saga dataclass through its steps, publishing commands to execute each step and, on failure, compensating already-completed steps in reverse order. An OrderFulfillmentSaga example shows this applied to a real workflow:

def define_steps(self, data: Dict) -> List[SagaStep]:
    return [
        SagaStep(
            name="reserve_inventory",
            action="InventoryService.ReserveItems",
            compensation="InventoryService.ReleaseReservation"
        ),
        SagaStep(
            name="process_payment",
            action="PaymentService.ProcessPayment",
            compensation="PaymentService.RefundPayment"
        ),
        SagaStep(
            name="create_shipment",
            action="ShippingService.CreateShipment",
            compensation="ShippingService.CancelShipment"
        ),
        SagaStep(
            name="send_confirmation",
            action="NotificationService.SendOrderConfirmation",
            compensation="NotificationService.SendCancellationNotice"
        )
    ]

Downstream services close the loop by publishing SagaStepCompleted, SagaStepFailed, or SagaCompensationCompleted events back to the orchestrator - an example InventoryService handler shows a step reserving inventory, then reporting success or failure so the orchestrator knows whether to advance or start compensating.

A choreography-based alternative subscribes directly to domain events (OrderCreated, InventoryReserved, PaymentProcessed, ShipmentCreated) and their failure counterparts, publishing the next step's event without a central coordinator. A fourth template adds step timeouts, scheduling a timeout check that fails a step still "executing" past its deadline.

The skill also names durable execution frameworks (like DBOS) as an alternative: instead of building saga infrastructure (stores, event publishers, compensation tracking) from scratch, a durable execution runtime persists workflow state automatically, retries failed steps, and resumes from the last checkpoint after crashes - saga-like reliability without managing the coordination infrastructure yourself.

Use this skill when coordinating multi-service transactions, implementing compensating transactions, managing long-running business workflows, handling failures in distributed systems, building order fulfillment processes, or implementing approval workflows. It works well alongside event-sourcing-architect, workflow-automation, and dbos-* skills.

Do not use it for tasks unrelated to saga orchestration or that need a different domain or tool outside this scope.

Inputs are the business process to coordinate (its steps, their actions, and their compensating actions). Output is either working orchestration code or a diagnosis of a failing saga implementation. The skill also bundles a resources/implementation-playbook.md reference for more detailed examples. Best practices: make every step idempotent so it's safe to retry, design compensations carefully since they must actually work, use correlation IDs for tracing across services, implement timeouts rather than waiting forever, and log everything for debugging. Avoid assuming instant completion, skipping compensation testing (the most critical part to test), tightly coupling services instead of using async messaging, or ignoring partial failures.

Backend and distributed-systems engineers building multi-service transactions - order fulfillment, approval workflows, or any process that must roll back cleanly across services on failure. Further pattern background is available in the Saga Pattern reference at microservices.io and in Designing Data-Intensive Applications, both cited as source reading.