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","Bash"]

Checking Completeness

Before doing anything else, invoke the connect skill to resolve TOKEN, BOARD_ID, ORG_ID, and BASE_URL. Then invoke the learn-eventmodelers-api skill to load the full API reference. Do not proceed until both skills have been loaded.

Board Context

Before starting, read the current board state to drive the analysis from what is actually on the board rather than relying solely on conversation context:

# All nodes (events, commands, read models, screens)
curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=EVENT"
curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=COMMAND"
curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=READMODEL"

Use these results as the source of truth for the completeness check.

Before treating any nodes as duplicates: check each node's data.linkedTo field (see learn-eventmodelers-api). A node with linkedTo set is an intentional linked copy of another node — placed elsewhere on the timeline for readability, not a modeling defect. When two or more nodes share a title/type:

• If any of them carries linkedTo, do not report a duplicate. This is expected, not a gap.
• Never propose deleting, suppressing, or "cleaning up" either node in a linked pair. Specifically, never target the node that has no linkedTo (the original) for removal — copies reference it via moveToWidget=<originNodeId>, so deleting it breaks every copy.
• Only flag same-titled nodes as an actual duplicate gap when none of them has linkedTo — i.e., they are genuinely two independent, unlinked nodes describing the same concept.

After the analysis, use the handle-comment skill to post findings on relevant nodes — TASK for required fixes, QUESTION for gaps that need clarification.

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 Slice Coverage

Every column that holds a COMMAND or READMODEL node must have a slice defined (a SLICE_BORDER node on that column) — otherwise it can never be built as a feature. Skip columns whose COMMAND/READMODEL node has data.linkedTo set: it's a linked copy (see Board Context above), and only the original's column needs a slice.

curl -s -H "x-token: $TOKEN" -H "x-board-id: $BOARD_ID" \
  "$BASE_URL/api/org/$ORG_ID/boards/$BOARD_ID/nodes?type=SLICE_BORDER"

Cross-reference each COMMAND/READMODEL node's column against the columnId of the SLICE_BORDER nodes:

Column: CreateOrder (COMMAND)
Slice defined? Yes — "Place Order"
Status: Covered

Column: OrderStatusView (READMODEL)
Slice defined? No
Status: Missing slice — flag as gap

Column: ConfirmOrder (COMMAND, linkedTo set — copy of the original in another column)
Slice defined? N/A — linked copy, exempt
Status: Skip

5. 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 

6. 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 

7. 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

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)
    - Customer must select payment method

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

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)
    - Payment method must be valid

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

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!

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]

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

---

### Step 2: ConfirmOrder

**Preconditions** (depends on Step 1):
- OrderCreated event exists 

**Postconditions**:
- OrderConfirmed event exists with fields: [list]

--- [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 |  |

---

## Slice Coverage

| Column | Node | Has Slice? | Status |
|--------|------|-----------|--------|
| 1 | CreateOrder (COMMAND) | Yes — "Place Order" |  |
| 2 | OrderStatusView (READMODEL) | No |  Missing slice |
| 3 | ConfirmOrder (COMMAND, linked copy) | N/A |  Exempt (linkedTo set) |

---

## 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

---

## 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
• Every column with a COMMAND or READMODEL node has a slice defined (unless it's a linked copy)
• 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

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 or is marked as generated) 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 COMMAND/READMODEL column has a slice defined, except linked copies

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)
False duplicate	Two nodes share a title	Check data.linkedTo on both before reporting — a linked copy is intentional, not a gap
Missing slice	COMMAND/READMODEL column with no SLICE_BORDER	Define a slice for that column (unless it's a linked copy)

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