Event-Driven Architect

Canonical Vocabulary

Dispatch

design <domain or workflow>

review <architecture or code path>

contract <event>

reliability <flow>

migration <change>

Mode Menu

design order fulfillment across payments, inventory, and shipping

review event flow for user-created -> email sync

contract invoice.paid

reliability retry strategy for webhook ingestion

migration move monolith side effects to events

When to Use

• Designing async workflows across services or bounded contexts
• Choosing event contracts, partition keys, or consumer responsibilities
• Introducing outbox, retry, replay, or dead-letter handling
• Reviewing whether an event system is resilient or over-coupled
• Planning migration from synchronous side effects to durable events

Classification Logic

1. If the task is synchronous API design, request-response contracts, or CRUD endpoint shape, use api-designer.
2. If the task is batch ETL, warehouse movement, or analytics-oriented transformation, use data-pipeline-architect.
3. If the task is broker installation, vendor-specific setup, or platform operations, use the relevant platform or devops skill.
4. If the workflow is ambiguous, first classify whether the system is centered on durable facts, asynchronous coordination, and replay-safe consumers. Only stay in this skill when the answer is yes.

Progressive Disclosure

• Keep

  SKILL.md

  focused on routing, operator steps, and non-negotiable constraints.
• Read reference files as indicated instead of loading everything at once.
• Load

  references/event-vs-command.md

  when the main question is whether something should be an event, command, or synchronous call.
• Load

  references/failure-modes.md

  when the task involves retries, replay, ordering, poison messages, or dead-letter handling.
• Load

  references/saga-comparison.md

  when choosing choreography, orchestration, or compensating workflows.
• Load

  references/output-templates.md

  when formatting architecture, contract, reliability, or migration outputs.

Instructions

Mode: Design

1. Identify the business facts that should become events. Name them in past tense.
2. Separate facts from commands and queries.
3. Read

   references/event-vs-command.md

   if the fact-vs-command boundary is unclear.
4. Define the producer, topic, partition key, consumers, and contract for each event.
5. Specify ordering requirements and where ordering does not matter.
6. Read

   references/saga-comparison.md

   when the workflow spans multiple services or compensating actions.
7. Produce an architecture with failure handling, replay, and observability using

   references/output-templates.md

   as needed.

Mode: Review

1. Read the event catalog, code path, or architecture diagram.
2. Check for hidden synchronous coupling, missing idempotency, weak contract ownership, or undefined replay behavior.
3. Flag places where an event stream is being misused for request-response semantics.
4. Read

   references/failure-modes.md

   when the review touches ordering, replay, retries, or consumer safety.
5. Present findings by severity.

Mode: Contract

1. Define required fields, producer, ownership, ordering expectations, and versioning strategy.
2. State which fields are identifiers, business facts, and metadata.
3. Prefer additive evolution; document deprecation windows for consumers.
4. Read

   references/event-vs-command.md

   if the proposed contract still looks like a command or query.

Mode: Reliability

1. Read

   references/failure-modes.md

   .
2. Design retry policy, backoff, poison-message handling, and dead-letter routing.
3. Specify idempotency strategy for consumers and handlers.
4. Define replay safety and operator controls.

Mode: Migration

1. Map the current synchronous side effect or legacy event flow.
2. Introduce the new event path behind explicit checkpoints.
3. Read

   references/output-templates.md

   for migration checkpoints and cutover framing.
4. Keep rollback simple by preserving the old path until the new path proves stable.

Output Requirements

• Every design must identify producer, topic, partition key, consumers, and failure strategy.
• Every contract must state ownership and versioning rules.
• Every reliability plan must include idempotency and dead-letter handling.

Reference File Index

references/event-vs-command.md

references/failure-modes.md

references/saga-comparison.md

references/output-templates.md

Critical Rules

1. Model business events as facts in past tense, not commands.
2. Consumers must be idempotent whenever retries or replay are possible.
3. Use the outbox pattern when publishing events from transactional database changes.
4. Do not use an event bus for low-latency request-response requirements that need immediate consistency.
5. Event contracts should evolve additively whenever possible.

Scaling Strategy

• small: Keep the design narrow. Define the minimum event set, one ownership boundary, and one reliability strategy before expanding.
• medium: Add explicit contract ownership, partition strategy, replay rules, and a clear saga choice for multi-service or mixed batch-plus-event workflows. Avoid hiding synchronous dependencies behind event terminology.
• large: Sequence cross-domain programs and migrations by bounded context. Start with one proven event path, then expand consumer batches and downstream automation only after replay, dead-letter handling, and observability are operator-safe.

Scope Boundaries