event-modeling

What this skill does

# Event Modeling

**Version:** 1.0.0
**Portability:** High

---

## Objective

Teaches Event Modeling facilitation based on Martin Dilger's "Understanding Eventsourcing" methodology, enabling systematic discovery of business domains and design of event-sourced systems through structured conversation.

**Purpose:** Reveal hidden domain knowledge, create shared understanding, and design systems that "don't lose information" through immutable event streams.

**Scope:**
- **Included:** Two-phase process (discovery → workflow), seven-step workflow design, four event patterns, vertical slicing, facilitation techniques
- **Excluded:** Implementation details, database schemas, technology choices, API design

---

## Core Principles

### Principle 1: Not Losing Information (Prime Directive)

**The Principle:** Store what happened (events), not just current state. Events are immutable facts that can be replayed, analyzed, and projected.

**Why this matters:** State-only systems lose the "why" behind current state. Event streams preserve full history, enabling audit trails, temporal queries, and business intelligence impossible with CRUD.

**How to apply:**
- Capture events when things happen
- Never delete or modify events (append-only)
- Build read models by projecting from event streams
- Every state change leaves an event trail

**Example:**
```
# ❌ State-only (information lost)
User { balance: $50 }
# Can't answer: How did they get $50? What transactions occurred?

# ✓ Event stream (complete history)
UserRegistered { userId: 123, initialBalance: $0 }
MoneyDeposited { userId: 123, amount: $100, timestamp: T1 }
MoneyWithdrawn { userId: 123, amount: $30, timestamp: T2 }
MoneyWithdrawn { userId: 123, amount: $20, timestamp: T3 }

# Can answer: How? When? Why? What sequence?
# Current state: Project events → balance = $50
```

### Principle 2: Event Modeling Reveals Understanding (Process Over Documentation)

**The Principle:** Event modeling is a structured conversation that surfaces hidden assumptions and creates shared understanding. You cannot skip steps because you think you understand.

**Why this matters:** Domain experts have tacit knowledge they don't know they have. The systematic process of event modeling extracts this knowledge through probing questions.

**How to apply:**
- Follow all seven steps (no shortcuts)
- Ask "And then what happens?" relentlessly
- Challenge assumptions (even obvious ones)
- Use business language, not technical jargon
- Facilitate conversation, don't dictate solutions

**Example of revelation:**
```
Facilitator: "What happens after the order is placed?"
Expert: "We fulfill it."
Facilitator: "And then what happens?"
Expert: "Well, first we check inventory..."
Facilitator: "And then?"
Expert: "If items are in stock, we reserve them."
Facilitator: "What if items aren't in stock?"
Expert: "Oh! We backorder them. I guess we need BackorderCreated event..."
# ↑ Hidden complexity revealed through questioning
```

### Principle 3: Events Are Past-Tense Facts in Business Language

**The Principle:** Events are immutable facts that happened, named in past tense using domain language that business experts understand.

**Why this matters:** Events form the foundation of system behavior and audit logs. Clear, business-aligned names make the system comprehensible to non-technical stakeholders.

**Event naming rules:**
- Past tense (UserRegistered, not RegisterUser)
- Business language (OrderPlaced, not CreateOrderCommand)
- Specific (ItemAddedToCart, not CartUpdated)
- Immutable facts (never change event names or delete events)

**How to apply:**
```
❌ Bad (technical, present tense):
- ProcessPayment
- UpdateUser
- DeleteItem

✓ Good (business, past tense):
- PaymentReceived
- EmailAddressChanged
- ItemRemovedFromCart
```

### Principle 4: Two-Phase Process (Discovery Then Design)

**The Principle:** Start with broad domain discovery before diving deep into any single workflow.

**Why this matters:** Jumping into detailed workflow design without understanding the broader domain leads to siloed thinking and missing connections between workflows.

**The Two Phases:**
1. **Domain Discovery:** What does the business do? Who are the actors? What are the major processes?
2. **Workflow Design:** For each workflow, follow seven steps to design events, commands, read models, automations.

**How to apply:**
```
# Phase 1: Domain Discovery (broad)
- Business: E-commerce platform
- Actors: Customers, Sellers, Admins
- Major processes: Product browsing, ordering, payment, fulfillment, returns
- External systems: Stripe (payment), ShipStation (shipping)
- Workflows to model: Order placement, Returns, Inventory management
- Start with: Order placement (most critical)

# Phase 2: Workflow Design (deep, one at a time)
- Order placement workflow: User goal → Events → Commands → Read Models → Automations
- Returns workflow: (separate branch, after order placement)
- Inventory management: (separate branch, after returns)
```

---

## Constraints and Boundaries

### DO (Facilitation):
- Follow all seven steps in workflow design (no shortcuts)
- Ask "And then what happens?" after every event
- Use business language (not technical jargon)
- Challenge assumptions (even obvious ones)
- Ensure information completeness (every read model field traces to events)
- Design one workflow at a time (don't jump between)
- Focus on behavior and business rules

### DON'T (Facilitation):
- Skip steps because you think you know enough
- Make architecture decisions during event modeling
- Discuss technical implementation (databases, APIs, frameworks)
- Rush to documentation
- Assume you understand domain better than expert
- Design workflows simultaneously (do one at a time)

### DO (Event Design):
- Name events in past tense (OrderPlaced, UserRegistered)
- Use business language domain experts understand
- Make events immutable facts
- Include relevant data in events (what, when, who)
- Find right granularity (not too coarse, not too fine)
- Record domain facts only (true on any machine — no file paths, hostnames, PIDs)

### DON'T (Event Design):
- Use present tense (ProcessPayment → PaymentProcessed)
- Use technical language (CreateOrderDTO → OrderCreated)
- Modify or delete events (append-only)
- Include implementation details in event names
- Make events too broad (DataUpdated) or too narrow (FieldXChanged)
- Have commands depend on read models (commands use user inputs + event stream)
- Include runtime context in events (file paths, hostnames, PIDs, working directories)

**Rationale:** Event modeling is a facilitation technique for revealing domain knowledge, not a technical design exercise. Keep it focused on business behavior.

---

## Usage Patterns

### Pattern 1: Complete Event Modeling Process

**Scenario:** Starting a new project or major feature.

**Phase 1: Domain Discovery**

**Questions to ask:**
1. What does this business/system do?
2. Who are the actors (roles, goals)?
3. What are the major processes?
4. What external systems exist?
5. What workflows should we model?
6. Which workflow should we start with? (and why)

**Example (E-commerce):**
```
1. Business: Online marketplace connecting sellers and buyers
2. Actors:
   - Customers (buy products)
   - Sellers (list products, fulfill orders)
   - Admins (moderate, handle disputes)
3. Major processes:
   - Product catalog management
   - Order placement and fulfillment
   - Payment processing
   - Returns and refunds
   - Shipping and tracking
4. External systems:
   - Stripe (payments)
   - ShipStation (shipping)
   - Sendgrid (email)
5. Workflows to model:
   - Order placement (critical path)
   - Product listing
   - Returns processing
6. Start with: Order placement (generates revenue, most complex)
```

**Output:** `docs/event_model/domain/overview.md`

**Phase 2: Workflow Design (per workflow)**

**The Seven Steps:**

**Step 1: Identify User Goal**
```
Question: "What is the user trying to accomplish?"