saga-orchestration

Saga Orchestration

Patterns for managing distributed transactions and long-running business processes without two-phase commit.

Inputs and Outputs

What you provide:

• Service boundaries and ownership (which service owns which step)
• Transaction requirements (which steps must be atomic, which can be eventual)
• Failure modes for each step (transient vs. permanent, retry policy)
• SLA requirements per step (informs timeout configuration)
• Existing event/messaging infrastructure (Kafka, RabbitMQ, SQS, etc.)

What this skill produces:

• Saga definition with ordered steps, action commands, and compensation commands
• Orchestrator or choreography implementation for your chosen pattern
• Compensation logic for each participant service (idempotent, always-succeeds)
• Step timeout configuration with per-step deadlines
• Monitoring setup: state machine metrics, stuck saga detection, DLQ recovery

---

When to Use This Skill

• Coordinating multi-service transactions without distributed locks
• Implementing compensating transactions for partial failures
• Managing long-running business workflows (minutes to hours)
• Handling failures in distributed systems where atomicity is required
• Building order fulfillment, approval, or booking processes
• Replacing fragile two-phase commit with async compensation

---

Detailed section: Core Concepts

Moved to references/details.md.

Detailed section: Templates

Moved to references/details.md.

Best Practices

Do's

• Make every step idempotent — Commands may be replayed on broker reconnect
• Design compensations carefully — They are the most critical code path
• Use correlation IDs — The saga_id must flow through every event and log
• Implement per-step timeouts — Never wait indefinitely for a participant reply
• Log state transitions — saga_id, step_name, old_state → new_state on every change
• Test compensation paths explicitly — Inject failures at each step index in integration tests