Event Modeling

Event Modeling

Value: Communication -- event modeling is a structured conversation that surfaces hidden domain knowledge and creates shared understanding between humans and agents before any code is written.

Purpose

Teaches the agent to facilitate event modeling sessions following Martin Dilger's "Understanding Eventsourcing" methodology. Produces a complete event model (actors, events, commands, read models, automations, slices) that drives all downstream implementation. The model lives in docs/event_model/.

Practices

Two-Phase Process: Discovery Then Design

Never jump into detailed workflow design without broad domain understanding first. Phase 1 maps the territory; Phase 2 explores each region.

Phase 1 -- Domain Discovery. Identify what the business does, who the actors are, what major processes exist, what external systems integrate, and which workflows to model. Ask these questions of the user; do not assume answers. Output: docs/event_model/domain/overview.md.

Phase 2 -- Workflow Design. For each workflow, follow the 9-step process. You MUST follow references/nine-steps.md for the full methodology. Design one workflow at a time. Complete all 9 steps before starting the next workflow. Output: docs/event_model/workflows/<name>/overview.md plus individual slice files in slices/.

The Prime Directive: Not Losing Information

Store what happened (events), not just current state. Events are immutable past-tense facts in business language. Every read model field must trace back to an event. If a field has no source event, something is missing from the model.

Event Design Rules

1. Name events in past tense using business language: OrderPlaced, not PlaceOrder or CreateOrderDTO 2. Events are immutable facts -- never modify or delete 3. Include relevant data: what happened, when, who/what caused it 4. Find the right granularity -- not DataUpdated (too broad) and not FieldXChanged (too narrow) 5. Commands depend on user inputs and the event stream, not read models. Read models serve views and automations only. 6. Events record domain facts (true on any machine). Runtime context (file paths, hostnames, PIDs, working directories) does not belong in event data.

The Four Patterns

Every event-sourced system uses these patterns. Each pattern maps to one vertical slice.

1. State Change: Command -> Event. The only way to modify state. A command may produce multiple events as part of a single operation. 2. State View: Events -> Read Model. How the system answers queries. When the domain supports concurrent instances, use collection types in read model fields, not singular values. Commands derive their inputs from user-provided data and the event stream — never from read models. No ReadModel → Command edges should appear in diagrams. If a command needs to check whether something already happened (e.g., idempotency), it checks the event stream, not a read model. Read models represent meaningful domain projections. Infrastructure preconditions ("does directory exist?", "is service running?") that are implicit in the command's execution context do not need their own read model. 3. Automation: Event -> Read Model (todo list) -> Process -> Command -> Event. Background work triggered by events. Requires all four components: triggering event, read model consulted, conditional process logic, and resulting command. If there is no read model and no conditional logic, it is NOT an automation — it is a command producing multiple events. Must have clear termination conditions. 4. Translation: External Data -> Internal Event. Anti-corruption layer for workflow-specific external integrations. Generic infrastructure shared by all workflows (event persistence, message transport) is NOT a Translation — it is cross-cutting infrastructure that belongs outside the event model.

Required Layers Per Slice Pattern

Each slice pattern implies a minimum set of architectural layers. A slice is not complete until all required layers are implemented and wired together.

• State View: infrastructure (read events/data from store) + domain (projection/query logic) + presentation (render or return result to caller) + application wiring (connect layers end-to-end)
• State Change: presentation (accept user input or external request) + domain (command validation and business rules) + infrastructure (persist resulting events/data) + application wiring (connect layers end-to-end)
• Automation: infrastructure (detect triggering condition — timer, external event, threshold) + domain (policy/decision logic) + infrastructure (execute resulting action — send message, write data, call service) + application wiring (connect trigger to policy to action)
• Translation: infrastructure (receive from external system) + domain (mapping/transformation logic) + infrastructure (deliver to target system) + application wiring (connect inbound adapter to mapper to outbound adapter)

When decomposing a slice, verify that your acceptance criteria and task breakdown cover every required layer. A slice that only implements domain logic without presentation or infrastructure is incomplete — it is a component, not a vertical slice.

GWT Scenarios

After workflow design, generate Given/When/Then scenarios for each slice. These become acceptance criteria for implementation.

Command scenarios: Given = prior events establishing state. When = the command with concrete data. Then = events produced OR an error (never both).

View scenarios: Given = current projection state. When = one new event. Then = resulting projection state. Views cannot reject events.

Critical distinction: GWT scenarios test business rules (state-dependent policies), not data validation (format/structure checks that belong in the type system). If the type system can make the invalid state unrepresentable, it is not a GWT scenario.

You MUST use references/gwt-template.md for the full scenario format and examples.

Application-Boundary Acceptance Scenarios

Every vertical slice MUST include at least one GWT scenario defined at the application boundary:

• Given: The system is in a known state (prior events, seed data, configuration)
• When: A user (or external caller) interacts through the application's external interface — the specific interface depends on the project (HTTP endpoint, CLI command, message queue consumer, UI action, etc.)
• Then: The result is observable at that same boundary — a response, output, rendered state change, emitted event, etc.

A GWT scenario that can be satisfied entirely by calling an internal function in a unit test describes a unit-level specification, not a slice acceptance criterion. Slice acceptance criteria must exercise the path from external input to observable output.

Acceptance Test Strategy

Where the application boundary is programmatically testable — HTTP endpoints, CLI output parsing, headless browser automation, message queue assertions, API contract tests, etc. — write automated acceptance tests that exercise the full GWT scenario from external input to observable output. These tests provide fast feedback and serve as living documentation of slice behavior.

Where automated boundary testing is not feasible (complex GUI interactions, hardware-dependent behavior, visual/aesthetic verification), document what the human should manually verify: the specific steps to perform and the expected observable result. This manual verification checklist becomes part of the slice's definition of done.

Slice Independence

Slices sharing an event schema are independent. The event schema is the shared contract. Command slices test by asserting on produced events; view slices test with synthetic event fixtures. Neither needs the other to be implemented first. No artificial dependency chains between slices.

Model Validation

After GWT scenarios are written, validate the model for completeness:

1. Every read model field traces to an event 2. Every event has a triggering command, automation, or translation 3. Every command has documented rejection conditions (business rules) 4. Every automation has a termination condition 5. GWT Given/When/Then clauses do not reference undefined elements

When gaps are found, ask the user to clarify, create the missing element, and re-validate. Do not proceed with gaps remaining.

Facilitation Mindset

You are a facilitator, not a stenographer. Ask probing questions. Challenge assumptions. Keep asking "And then what happens?" after every event, every command, every answer. Use business language, not technical jargon. Do not discuss databases, APIs, frameworks, or implementation during event modeling. The only exception: note mandatory third-party integrations by name and purpose.

Do:

• Follow all steps in order -- the process reveals understanding
• Ask "And then what happens?" relentlessly
• Use concrete, realistic data in all examples and scenarios
• Design one workflow at a time
• Ensure information completeness before proceeding
• Ask "Can there be more than one of these at the same time?" for read model fields
• Verify automations have all four components before labeling them as such

Do not:

• Skip steps because you think you know enough
• Make architecture or implementation decisions during modeling
• Write GWT scenarios for data validation (use the type system)
• Design multiple workflows simultaneously
• Proceed with gaps in the model

Enforcement Note

• Standalone mode: Advisory. The agent follows the nine-step methodology

by convention.

• Pipeline mode: Gating. Incomplete models (missing GWT scenarios,

undefined automations) block slice decomposition.

Hard constraints:

• Do not proceed with gaps in the model: [RP]

Constraints

• "MUST follow nine-steps.md": Following the nine steps means executing

each step's specific activities and producing its specific outputs. It does not mean reading the reference and claiming "I followed the spirit." Each step has defined outputs -- produce them.

• "Do not design multiple workflows simultaneously": This includes

starting "discovery" for Workflow 2 while Workflow 1's steps are incomplete. Discovery IS design. If you're gathering information about a future workflow, you're designing it.

• Facilitation vs. stenography: Facilitation means asking questions that

help the domain expert discover things they haven't articulated yet. It does not mean asking leading questions that guide toward your preferred answer. The test: could the expert's answer genuinely surprise you? If not, you're leading, not facilitating.

Verification

After completing event modeling work, verify:

• [ ] Domain overview exists at docs/event_model/domain/overview.md with

actors, workflows, external integrations, and recommended starting workflow

• [ ] Each designed workflow has docs/event_model/workflows/<name>/overview.md

with all 9 steps completed

• [ ] All events are past tense, business language, immutable facts
• [ ] Every read model field traces to a source event
• [ ] Every event has a trigger (command, automation, or translation)
• [ ] Automations have all four components (event, read model, conditional logic, command)
• [ ] Read model fields use collection types when domain supports concurrent instances
• [ ] No cross-cutting infrastructure modeled as Translation slices
• [ ] GWT scenarios exist for each slice (inline in docs/event_model/workflows/<name>/slices/*.md) with concrete data
• [ ] GWT error scenarios test business rules only, not data validation
• [ ] Slices sharing an event schema are independently testable (no

artificial dependency chains)

• [ ] No gaps remain in the model after validation

If any criterion is not met, revisit the relevant practice before proceeding.

Dependencies

This skill works standalone. For enhanced workflows, it integrates with:

• domain-modeling: Events reveal domain types (Email, Money, OrderStatus)

that the domain modeling skill refines

• tdd: Each vertical slice maps to one TDD cycle
• architecture-decisions: Event model informs architecture; ADRs should

not be written during event modeling itself

• task-management: Workflows map to epics, slices map to tasks

Missing a dependency? Install with:

npx skills add jwilger/agent-skills --skill domain-modeling

GWT Scenario Templates and Examples

GWT (Given/When/Then) scenarios are acceptance criteria for vertical slices. They define what "done" means for each slice. Write them after workflow design is complete.

Command Scenario Template (State Change Pattern)

### Scenario: <Descriptive title>

**Given** (prior events):
- EventName { field: "value", field2: "value2" }

**When** (command):
- CommandName { input1: "value", input2: "value" }

**Then** (events produced):
- EventName { field: "value", timestamp: "ISO-8601" }

For error cases, Then contains an error message and NO events:

### Scenario: <Error case title>

**Given** (prior events):
- EventName { field: "value" }

**When** (command):
- CommandName { input1: "value" }

**Then** (error - no events):
- Error: "Descriptive business error message"

View Scenario Template (State View Pattern)

### Scenario: <Event updates projection title>

**Given** (current projection state):
- ProjectionName { field1: "value", field2: 100 }

**When** (event to process):
- EventName { relevantField: "value" }

**Then** (resulting projection state):
- ProjectionName { field1: "newValue", field2: 70 }

Views CANNOT reject events. There are no error cases for view scenarios.

Automation Scenario Template

### Scenario: <Automation trigger title>

**Given** (prior events establishing state):
- EventName { field: "value" }

**When** (trigger event):
- TriggerEvent { field: "value" }

**Then** (automation issues command, producing events):
- ResultEvent { field: "value" }

Examples

Command -- Happy Path

### Scenario: Successfully place an order

**Given** (prior events):
- CartCreated { cartId: "CART-001", customerId: "CUST-123" }
- ItemAddedToCart { cartId: "CART-001", productId: "PROD-42", quantity: 2, unitPrice: 29.99 }
- ShippingAddressValidated { cartId: "CART-001", address: "123 Main St, Springfield" }

**When** (command):
- PlaceOrder { cartId: "CART-001", paymentMethod: "card_ending_4242" }

**Then** (events produced):
- OrderPlaced { orderId: "ORD-789", cartId: "CART-001", customerId: "CUST-123", totalAmount: 59.98, timestamp: "2026-01-15T10:30:00Z" }

Command -- Business Rule Error

### Scenario: Cannot place order with empty cart

**Given** (prior events):
- CartCreated { cartId: "CART-001", customerId: "CUST-123" }

**When** (command):
- PlaceOrder { cartId: "CART-001", paymentMethod: "card_ending_4242" }

**Then** (error - no events):
- Error: "Cannot place order: cart CART-001 contains no items"

View -- Projection Update

### Scenario: Order placement updates order summary view

**Given** (current projection state):
- OrderSummary { customerId: "CUST-123", activeOrders: 0, totalSpent: 0.00 }

**When** (event to process):
- OrderPlaced { orderId: "ORD-789", customerId: "CUST-123", totalAmount: 59.98, timestamp: "2026-01-15T10:30:00Z" }

**Then** (resulting projection state):
- OrderSummary { customerId: "CUST-123", activeOrders: 1, totalSpent: 59.98 }

Business Rules vs Data Validation

Before writing an error scenario, apply this test:

1. Does this error depend on existing system state (what events occurred)?

• Yes -> Business rule -> Write a GWT scenario
• No -> Probably data validation -> Type system handles it

2. Can the type system make the invalid state unrepresentable?

• Yes -> Not a GWT scenario (use Email type, NonEmptyString, etc.)
• No (depends on runtime state) -> GWT scenario

3. Would a different business potentially have different rules here?

• Yes -> Business rule -> GWT scenario
• No (universal like "email needs @") -> Type system

Write GWT scenarios for: "Cannot archive an already-archived task", "Cannot withdraw more than balance", "Maximum 100 items per order".

Do NOT write GWT scenarios for: "Email must contain @", "Title cannot be empty", "Amount must be positive". These belong in domain types.

Quality Checklist

For all scenarios:

• [ ] Uses concrete, realistic values (not "valid user" or "some amount")
• [ ] Tests one behavior
• [ ] Is independent of other scenarios
• [ ] Uses business language matching event model terminology

For command scenarios:

• [ ] Given contains only events with all fields
• [ ] When contains exactly one command with all inputs
• [ ] Then contains either events OR an error, never both
• [ ] Error cases test business rules, not data validation

For view scenarios:

• [ ] Given contains complete projection state before processing
• [ ] When contains exactly one event
• [ ] Then contains complete projection state after processing
• [ ] No error cases (views cannot reject)

The Nine-Step Workflow Design Process

Follow ALL nine steps for each workflow. Do not skip steps. Do not combine steps. The process reveals understanding that shortcuts would miss.

Step 1: Identify the User Goal

Ask until the goal is crystal clear:

• "What exactly is the user trying to accomplish?"
• "What does success look like to them?"
• "What would make this fail?"

Do not proceed until the goal is unambiguous.

Step 2: Brainstorm Events

Sticky-note style -- capture all possible events without ordering:

• "What facts need to be recorded?"
• "What happened that we care about?"
• "What would an auditor want to know?"

Events must be past tense, business language, facts. Example: OrderPlaced, PaymentReceived, InventoryReserved.

Keep asking: "What else? What am I missing?"

Domain Facts vs. Runtime Context

Events must record domain facts — statements that are true regardless of which machine, process, or environment replays them. Runtime context does not belong in event data.

# Bad — runtime context leaks into the event:
ProjectInitialized {
  project_id: "abc-123",
  working_directory: "/home/dev/projects/myapp",   # machine-specific
  pid: 48291,                                       # process-specific
  hostname: "dev-laptop.local"                      # environment-specific
}

# Good — domain facts only:
ProjectInitialized {
  project_id: "abc-123",
  project_name: "myapp",
  initialized_by: "user-456",
  template: "web-app"
}

Test: "Would this field have the same value if the event were replayed on a different machine?" If no, it is runtime context and does not belong in the event.

Step 3: Order Events Chronologically

Arrange brainstormed events into the timeline -- the "plot" of the workflow.

• "What happens first?"
• "And then what happens?" (repeat until complete)
• Identify the happy path and alternative/error paths

Step 4: Create Wireframes

These wireframes do not need to represent the actual UI/UX of the application. Their purpose is to provide a complete accounting of what data a user can see and what actions a user can take from each screen.

For each user interaction point, create an ASCII wireframe showing:

• What data the user SEES (from read models)
• What data the user PROVIDES (command inputs)
• What actions the user can TAKE (buttons/triggers)

+-------------------------------+
|  Place Order                  |
+-------------------------------+
|  Items: [list from cart]      |
|  Shipping: [address]          |
|  Total: $XX.XX                |
|                               |
|  [Confirm Order]              |
+-------------------------------+

Every wireframe field must trace to an event field (displays) or a command input (inputs). If you cannot trace a field, something is missing.

Concurrency Check

If the domain supports concurrent instances (e.g., multiple orders, multiple journeys), wireframes should show lists or tables, not single-item views. Ask: "Can there be more than one of these in progress at the same time?"

Step 5: Identify Commands

For each event, determine the trigger:

• "What triggered this event?"
• "Who or what issued that command?"
• "What information did they provide?"
• "Under what circumstances would this NOT happen?"

Commands are imperative, present tense: PlaceOrder, ProcessPayment. Commands can fail; events cannot.

Step 6: Design Read Models

Read models exist to support data displayed on wireframes as well as data needed by automations. For each actor at each workflow point, and for each automation:

• "What does this person need to see?"
• "What information do they need to make decisions?"
• "What data does this automation need to determine its next action?"

Verify every read model field traces back to an event. Example:

OrderSummary:
  orderId       <- OrderPlaced.orderId
  items         <- ItemAdded, ItemRemoved events
  totalAmount   <- OrderPlaced.totalAmount
  status        <- OrderPlaced, PaymentReceived, OrderShipped events

If a field has no source event, the model is incomplete.

Concurrency Check

For each read model field, ask: "Can there be more than one of these active at the same time?" If the domain supports concurrent instances, use collection types, not singular values:

# Singular (only valid if business rule enforces one-at-a-time):
current_phase: string

# Collection (when concurrent instances exist):
active_journeys: [{journey_id, phase, started_at}, ...]

Command Independence

Commands derive their inputs from user-provided data and the event stream. Read models serve views and automations — they do NOT feed commands. If a command needs to know whether something already happened, it checks the event stream directly, not a read model.

• "Does the command rely on a read model to decide what to do?" → Wrong.

The command should check the event stream for prior events.

• "Is an idempotency guard querying a read model?" → Wrong. Check the

event stream for a duplicate event.

No Read Models for Infrastructure Preconditions

Read models represent meaningful domain projections — not infrastructure checks. If a precondition is purely about infrastructure state (does a directory exist? is a service running?), it does not need its own read model.

# Bad — infrastructure check modeled as a read model:
ReadModel: RepositoryExistence
  exists: boolean    ← RepositoryInitialized

# Good — command checks the precondition directly:
Command: InitializeProject
  Precondition: directory exists (infrastructure, not domain state)
  Produces: ProjectInitialized

Infrastructure preconditions are either: 1. Implicit in the command's execution context (the OS provides them) 2. Checked as part of the command handler's implementation

They do not need a domain read model.

Step 7: Find Automations

Look for automatic responses to events that involve decision-making:

• "Does anything happen automatically after this event?"
• "What business rules trigger other processes?"
• "Does the system need to check anything before acting?"

Pattern: Event -> Read Model (todo list) -> Process -> Command -> Event

All four components are required for a true Automation: 1. A triggering event 2. A read model (the "todo list") the process consults 3. Conditional logic that decides whether and how to act 4. A resulting command that produces new events

If there is no read model and no conditional logic — if the events are always unconditionally co-produced — it is NOT an Automation. Model it as a single Command slice with multiple output events.

Test: Ask "Can this automatic response ever be skipped or vary based on system state?" If no, it is co-production, not automation.

Every automation must have a clear termination condition. Watch for infinite loops.

Step 8: Map External Integrations

Identify external system interactions using the Translation pattern:

• "Does this workflow receive data from outside?"
• "Does this workflow send data to external systems?"

Note only names and general purposes. No technical details (APIs, webhooks, protocols). Example: "Stripe provides payment confirmation" -- not "Stripe webhook sends POST to /api/webhooks/stripe".

Data Flow Rules for Diagrams

When creating workflow diagrams, data flows follow these rules:

• Actor/UI → Command: User inputs flow into commands
• Command → Event: Commands produce events
• Event → Read Model: Events feed read model projections
• Read Model → Actor/UI: Read models serve views
• Event → Automation Read Model → Process → Command: Automations

consult read models, but the resulting command still checks the event stream for its own validation

There must be NO ReadModel → Command edges in any diagram. If you find one, the command is incorrectly depending on a read model.

Infrastructure vs. Domain Translations

Ask: "Is this integration specific to THIS workflow, or would every workflow need it?"

If every workflow needs it, it is cross-cutting infrastructure (persistence, messaging, logging) — NOT a Translation slice. Note it as an infrastructure dependency, not as a slice.

Step 9: Decompose into Vertical Slices

List all vertical slices grouped by pattern type:

• Command Slices: Each command that produces events
• View Slices: Each read model/projection
• Automation Slices: Each automatic process
• Translation Slices: Each external integration

A good slice is: a complete user interaction, independently valuable, testable in isolation, small enough for 1-2 days of work.

Bad slices: "Set up database" (technical, no user value), "Implement order system" (too broad), "Create Order table" (implementation detail).

Also not slices: cross-cutting infrastructure (e.g., "Persist Events to Database") that would appear identically in every workflow. Infrastructure is not business behavior — document it in the domain overview, not as workflow slices.

Slice Independence

Slices that share an event schema are independent — connected by the event contract, not by execution order. The event schema is the shared contract between a command slice that produces events and a view slice that consumes them.

# Bad — artificial dependency chain:
Slice 1: "Initialize Project" (must complete before Slice 2)
Slice 2: "Show Project Dashboard" (depends on Slice 1 running first)

# Good — independent slices sharing an event schema:
Slice 1: "Initialize Project" → produces ProjectInitialized event
Slice 2: "Project Dashboard" → projects from ProjectInitialized event
  (testable with synthetic ProjectInitialized fixtures, no Slice 1 needed)

• Command slices test by asserting on produced events (given prior

events, when command executes, then these events are produced)

• View slices test with synthetic event fixtures (given these events,

the projection shows this state)

• Neither slice needs the other to be implemented or running

Output Structure

docs/event_model/workflows/<name>/
  overview.md       # All 9 steps, workflow diagram, slice index
  slices/
    <slice-1>.md    # Pattern, diagram, details, GWT scenarios
    <slice-2>.md
    ...

Facilitation Questions Quick Reference

Domain Discovery: What does the business do? Who are the actors? What are the major processes? What external systems exist? Which workflow is most critical?

Events: What facts need recording? What happened here? Would the business need to know this?

Timeline: What happens first? And then? Can these happen in parallel?

Commands: Who initiates this? Is it user-triggered or automatic? What intent does this represent?

Read Models: What does this actor need to see? What queries do users run? Can there be multiple instances active simultaneously?

Automations: Does anything happen automatically? What business rules apply? Does this trigger other processes?

Edge Cases: What if this fails? What if the user cancels? What if the external system is down?