@eventmodelers/cli 0.0.1

package/stacks/modeling-kit/templates/.claude/skills/eventmodeling-checking-completeness/SKILL.md

@@ -0,0 +1,542 @@
+---
+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:
+
+```bash
+# 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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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.
+
+```bash
+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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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:
+
+```text
+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**:
+```text
+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:
+
+```markdown
+| 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:
+
+```text
+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:
+
+```markdown
+# 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](references/security-analysis-with-event-modeling.md)** — 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