eventmodeling-checking-completeness

name	eventmodeling-checking-completeness
description	Step 8 of Event Modeling - Completeness Check. Verify every field has origin and destination. Ensure complete event model before code generation. Use after all scenarios defined. Do not use for: architectural validation against event sourcing principles (use eventmodeling-validating-event-models) or elaborating Given-When-Then specs (use eventmodeling-elaborating-scenarios).
allowed-tools	["Write"]

Checking Completeness

Workflow

Perform comprehensive completeness check:

1. Field Origin & Destination Matrix

For every field in every event, verify source and use:

Event: OrderCreated

Field: orderId
Origin: Generated by system (UUID)
Destinations:
     OrderConfirmed event (references)
     OrderStatusView (displays)
     OrderListView (displays)
     OrderShipped event (references)
Status:  Complete

Field: customerId
Origin: CreateOrder command (from UI)
Destinations:
     OrderStatusView (displays)
     OrderListView (displays)
     Inventory System (knows who ordered)
Status:  Complete

Field: items[]
Origin: CreateOrder command (user selects)
Destinations:
     OrderStatusView (displays)
     Inventory System (what to reserve)
     Fulfillment System (what to ship)
Status:  Complete

Field: total
Origin: Calculated from items[] and unit prices
Destinations:
     OrderStatusView (displays)
     OrderListView (displays)
     PaymentSystem (amount to charge)
     Accounting (for reconciliation)
Status:  Complete

Field: shippingAddress
Origin: CreateOrder command (user enters)
Destinations:
     OrderStatusView (displays)
     Fulfillment System (where to ship)
     Carrier (delivery address)
Status:  Complete

Field: createdAt
Origin: System timestamp when event created
Destinations:
     OrderStatusView (displays)
     OrderListView (displays)
     Metrics (average order age)
Status:  Complete

2. Check All Commands

Verify every command input is captured:

Command: CreateOrder
Input: customerId, items[], shippingAddress
   customerId → OrderCreated.customerId
   items[] → OrderCreated.items
   shippingAddress → OrderCreated.shippingAddress
Status: All inputs captured 

Command: ConfirmOrder
Input: orderId, paymentMethod
   orderId → OrderConfirmed.orderId (implicit)
   paymentMethod → OrderConfirmed.paymentMethod
Status: All inputs captured 

Command: AuthorizePayment
Input: orderId, paymentId, authCode
   orderId → PaymentAuthorized.orderId (implicit)
   paymentId → PaymentAuthorized.paymentId
   authCode → PaymentAuthorized.authCode
Status: All inputs captured 

3. Check All Read Models

Verify read models have all needed data:

ReadModel: OrderStatusView
Needs to display:
     orderId ← OrderCreated
     customerId ← OrderCreated
     status ← OrderConfirmed, PaymentAuthorized, etc.
     items ← OrderCreated
     total ← OrderCreated
     createdAt ← OrderCreated
     confirmedAt ← OrderConfirmed
     paymentId ← PaymentAuthorized
     paymentMethod ← OrderConfirmed
     shipmentId ← OrderShipped
     trackingNumber ← OrderShipped
Status: All fields sourced 

ReadModel: OrderListView
Needs to display:
     orderId ← OrderCreated
     customerId ← OrderCreated
     total ← OrderCreated
     status ← OrderConfirmed, OrderCancelled, etc.
     createdAt ← OrderCreated
Status: All fields sourced 

4. Check Event Stream Completeness

Verify no "missing" events:

Scenario: Order from creation to delivery

Timeline:
1. OrderCreated  (from CreateOrder command)
2. OrderConfirmed  (from ConfirmOrder command)
3. PaymentAuthorized  (from AuthorizePayment processor command)
4. InventoryReserved  (from ReserveInventory processor command)
5. OrderShipped  (from CreateShipment processor command)
6. DeliveryConfirmed  (from MarkDelivered processor command)

Missing events? None identified 

Alternative paths:
- OrderCancelled  (can happen after OrderCreated or OrderConfirmed)
- PaymentFailed  (can happen during PaymentAuthorized)
- RefundInitiated  (can happen after PaymentFailed or OrderCancelled)

Status: All paths covered 

5. Check System Boundaries

Verify each system owns events:

Order System
Events: OrderCreated, OrderConfirmed, OrderCancelled 
Processor: None (triggers other systems)
Status: Clean ownership 

Payment System
Events: PaymentAuthorized, PaymentFailed, PaymentRefunded 
Processor: PaymentAuthorizer (listens to OrderConfirmed)
Status: Clean ownership 

Inventory System
Events: InventoryReserved, InventoryReleased 
Processor: InventoryReserver (listens to PaymentAuthorized)
Status: Clean ownership 

Fulfillment System
Events: OrderShipped, DeliveryConfirmed 
Processor: ShipmentCreator (listens to InventoryReserved)
Status: Clean ownership 

Notification System
Events: None (no persistence, info-only)
Processor: Notifier (listens to all events)
Status: Cross-cutting concern 

6. Define Workflow Step Contracts

Each workflow step is a contract between the previous step and the next. Document preconditions and postconditions:

Workflow Step 1: CreateOrder (Step Owns: Order Creation)

Preconditions (what must exist before this step):
    - Customer must exist
    - Products must exist in catalog
    - User must be authenticated

Postconditions (what exists after this step):
    - OrderCreated event exists
    - Event contains: orderId, customerId, items, total, shippingAddress, createdAt
    - Order state: Draft

Contract: Any system can assume if these postconditions are true,
            the order has been properly created through this step.

--- Workflow Step 2: ConfirmOrder (Step Owns: Order Confirmation)

Preconditions (depends on Step 1 postcondition):
    - OrderCreated event must exist ( from Step 1 contract)
    - Order must be in Draft state
    - Customer must select payment method

Postconditions (what exists after this step):
    - OrderConfirmed event exists
    - Event contains: orderId, paymentMethod, confirmedAt
    - Order state: Confirmed

Contract: Any system can assume if these postconditions are true,
            the order has been properly confirmed.

--- Workflow Step 3: AuthorizePayment (Step Owns: Payment Authorization)

Preconditions (depends on Step 2 postcondition):
    - OrderConfirmed event must exist ( from Step 2 contract)
    - Order must be in Confirmed state
    - Payment method must be valid

Postconditions (what exists after this step):
    - PaymentAuthorized event exists
    - Event contains: paymentId, authCode, amount
    - Payment state: Authorized

Contract: Once this postcondition is true, next steps can proceed
            without re-checking payment (trust the contract).

Why Contracts Matter for Parallel Development:

Team A: Works on CreateOrder (Step 1)
  → Knows postcondition: OrderCreated with specific fields
  → Knows other teams depend on this

Team B: Works on ConfirmOrder (Step 2)
  → Can start immediately, doesn't wait for Step 1 implementation
  → Just needs to know: "I expect OrderCreated event with these fields"
  → Writes tests that mock the OrderCreated event
  → When Step 1 is done, tests pass immediately

Team C: Works on AuthorizePayment (Step 3)
  → Can start immediately
  → Expects: OrderConfirmed event with these fields
  → When Step 2 is done, tests pass immediately

Result: 3 teams working in parallel instead of waiting sequentially!

7. Check Role Coverage

Verify that the Role Catalog (from Step 1) is fully exercised:

Role Coverage Matrix:

Human Roles:
Customer
     Has swimlane in storyboard (Step 3)
     Commands attributed: CreateOrder, ConfirmOrder, CancelOrder
     Read models consumed: OrderStatusView, OrderListView
     Scenarios reference this role
    Status:  Complete

Seller
     Has swimlane in storyboard (Step 3)
     Commands attributed: RespondToReview, ConfirmStock
     Read models consumed: SellerDashboardView
     Scenarios reference this role
    Status:  Complete

Support Agent
     Has swimlane in storyboard (Step 3)
     Commands attributed: OverrideOrderStatus
     No read models identified
     No scenarios reference this role
    Status:  Incomplete — needs read models and scenarios

System Actors:
Payment Gateway
     Commands attributed: AuthorizePayment, FailPayment
    Status:  Complete

Inventory System
     Commands attributed: ReserveInventory
    Status:  Complete

Validation rules:

• Every human role MUST have at least one command
• Every human role MUST have at least one read model/view
• Every human role MUST appear in at least one scenario (Step 7)
• Every system actor MUST have at least one command or processor trigger

If a role has zero commands → either the role is unnecessary (remove from catalog) or commands are missing (add them).

8. Check Field Traceability

Matrix of all fields origin → destination:

| Field | Event | Command | Read Model | Processor |
|-------|-------|---------|-----------|-----------|
| orderId | OrderCreated | - | All views | All |
| customerId | OrderCreated | CreateOrder | OrderStatusView | - |
| items | OrderCreated | CreateOrder | List/Status views | Inventory |
| total | OrderCreated | - | List/Status views | - |
| paymentId | PaymentAuthorized | AuthorizePayment | StatusView | Inventory |
| shipmentId | OrderShipped | CreateShipment | StatusView | Notification |
| trackingNumber | OrderShipped | - | TrackingView | Notification |

Status: All fields traceable 

9. Identify Gaps

Document any missing pieces:

Analysis: Are there any missing fields?
  - Estimated delivery date?
    → Need to add to OrderShipped event
    → Can be calculated from carrier
    → Add to ShipmentTrackingView

  - Cancellation reason?
    → Already in OrderCancelled event 

  - Payment failure reason?
    → Already in PaymentFailed event 

  - Refund status?
    → Need to track in RefundInitiated event
    → Add to PaymentStatusView

Actions taken:
   Add estimatedDelivery to OrderShipped
   Add refundStatus to PaymentStatusView
   Add refundInitiatedAt to OrderStatusView

Output Format

Present as:

# Completeness Check: [Domain Name]

## Workflow Step Contracts

### Step 1: CreateOrder

**Preconditions**:
- Customer exists in system
- Products exist in catalog

**Postconditions**:
- OrderCreated event exists with fields: [list]
- Order state is Draft

**Teams that depend on this contract**: [All downstream teams]

---

### Step 2: ConfirmOrder

**Preconditions** (depends on Step 1):
- OrderCreated event exists 
- Order in Draft state

**Postconditions**:
- OrderConfirmed event exists with fields: [list]
- Order state is Confirmed

--- [Continue for each workflow step]

---

## Field Traceability Matrix

### Events

| Event | Field | Origin | Destinations | Status |
|-------|-------|--------|-------------|--------|
| OrderCreated | orderId | System | ConfirmOrder, Views |  |
| OrderCreated | customerId | CreateOrder | All views |  |
| OrderCreated | items | CreateOrder | Inventory, Views |  |
| OrderCreated | total | Calculated | Views, Payment |  |
| OrderConfirmed | paymentId | AuthorizePayment | Views, Accounting |  |
| OrderShipped | trackingNumber | Carrier | TrackingView |  |

---

## System Ownership Verification

### Order System
- Events owned: OrderCreated, OrderConfirmed, OrderCancelled
- Completeness:  All order lifecycle events present

### Payment System
- Events owned: PaymentAuthorized, PaymentFailed, PaymentRefunded
- Completeness:  All payment states covered

---

## Command → Event Verification

| Command | Input | Event | Captured |
|---------|-------|-------|----------|
| CreateOrder | customerId, items, address | OrderCreated |  |
| ConfirmOrder | paymentMethod | OrderConfirmed |  |
| AuthorizePayment | paymentId, authCode | PaymentAuthorized |  |

---

## Read Model Coverage

### OrderStatusView
- All relevant event data included
- All user display needs met
- All processor decision fields present

### OrderListView
- Summary fields captured
- Filtering/sorting fields present
- Linked to OrderStatusView for details

---

## Role Coverage

### Human Roles

| Role | Swimlane | Commands | Read Models | Scenarios | Status |
|------|----------|----------|-------------|-----------|--------|
| Customer |  | CreateOrder, ConfirmOrder, CancelOrder | OrderStatusView, OrderListView |  5 scenarios | Complete |
| Seller |  | RespondToReview | SellerDashboardView |  2 scenarios | Complete |
| Support Agent |  | OverrideOrderStatus |  None |  None | Incomplete |

### System Actors

| Actor | Commands/Triggers | Status |
|-------|-------------------|--------|
| Payment Gateway | AuthorizePayment, FailPayment |  |
| Inventory System | ReserveInventory |  |

---

## Gap Analysis

### Issues Found
1. Estimated delivery date missing
   - Fix: Add to OrderShipped event
   - Type: string (ISO 8601 date)
   - Source: Calculated from carrier API
   - Status: Will add in next iteration

2. Refund tracking incomplete
   - Fix: Add RefundInitiated event timestamp
   - Fix: Add refund status to PaymentStatusView
   - Status: Will add in next iteration

### No Critical Gaps
- All events properly sourced
- All command inputs captured
- All read models have data
- Event flow complete
- System boundaries clear

---

## Readiness Assessment

**Overall Completeness**: 95%

**Blockers**: None

**Ready for Code Generation**:  YES

**Minor Improvements**:
- Add estimated delivery date (non-blocking)
- Enhance refund tracking (non-blocking)

**Recommendation**: Proceed to code generation phase.

Quality Checklist

• Every field has clear origin
• Every field has identified destinations
• All command inputs are captured
• All read models have sources
• Event flow is complete
• No events are missing
• System boundaries are clear
• Alternative paths covered
• Error paths documented
• Processors are identified
• No circular dependencies
• All scenarios have data sources
• Workflow step contracts defined for each step
• Each contract has explicit preconditions
• Each contract has explicit postconditions
• Dependencies between steps documented
• Teams can work in parallel based on contracts
• Every human role from the Role Catalog has at least one command
• Every human role has at least one read model/view
• Every human role appears in at least one scenario
• Every system actor has at least one command or processor trigger
• No role in the catalog is orphaned (zero usage across the model)

CRITICAL: Event vs Read Model Validation

• Reviewed every "calculated event": Is it a domain fact or pure calculation?
• No aggregation events: Totals, averages, counts are read models, NOT events
• Recalculated state identified: If a value changes multiple times, it's a read model
• Processor outputs categorized:
  • Facts → Events (e.g., PaymentAuthorized)
  • Calculations → Read Models (e.g., SellerRatingCalculated)
  • Notifications → No event/model (info-only)
• History tracking correct: Read models track history in history[], not as separate events

Completeness Criteria

The model is complete when: Every event field has a source (command or system) Every command input becomes event/state data Every read model field has event source All state transitions are covered Alternative flows are documented Error conditions are handled System boundaries are clear No "magic" data appears without source Data flows logically end-to-end All stakeholder needs are met Events are facts (immutable domain actions) Read models are projections (derived/calculated state) No calculated events exist (aggregations/totals are read models) Every role in the Role Catalog is exercised (has commands, views, and scenarios)

Common Incompleteness Issues

Issue	Example	Fix
Missing event	"No event for failure"	Add failure event
Orphaned data	"Field in view, not in event"	Add field to event
Circular flow	"A needs B, B needs A"	Redesign boundary
Missing field	"View needs date, event has none"	Add field to event
Unclear origin	"Where does this come from?"	Trace back to source
Calculated event	SellerRatingCalculated, InventoryTotal	Move to read model (recalculated state is projection)

Reference Documentation

• Security Analysis with Event Modeling — How to use the field traceability matrix and data flow visibility from this step to conduct a systematic security review: identifying trust boundaries, privilege escalation paths, and data exposure risks across the event model.

Next Steps

If completeness check passes: → Proceed to code generation

If gaps found: → Return to appropriate step to fix → Re-run completeness check