eventmodeling-storyboarding-events

name	eventmodeling-storyboarding-events
description	Step 3 of Event Modeling - Create UI storyboards/mockups showing what users see at each step. Capture all data fields needed from user perspective. Use after sequencing events. Do not use for: identifying commands or processor actions (use eventmodeling-identifying-inputs) or designing read models (use eventmodeling-identifying-outputs).
allowed-tools	["AskUserQuestion","Write"]

Storyboarding Events

Interview Phase (Optional)

When to Interview: Skip if the user has already specified: existing UI patterns or mockups to reference, critical data fields, and UI/UX preferences. Interview when these details haven't been discussed or when the user wants guidance on storyboarding depth.

Interview Strategy: Clarify UI needs, data priorities, and existing patterns to guide storyboard design. This ensures mockups capture all necessary fields without over-designing.

Critical Questions

When UI design guidance is needed:

1. Current UI State (Impact: Determines if you're designing from scratch or enhancing existing)

   • Question: "Do you have: (A) Existing UI/wireframes to reference, (B) Rough sketches, (C) Starting from scratch?"
   • Why it matters: Existing UI provides constraints and patterns; starting fresh allows more design freedom
   • Follow-up triggers: If (A) → ask to share; if (C) → ask about platform/technology

2. Most Critical Data Fields (Impact: Determines storyboard focus and detail level)

   • Question: "Which data fields are most important for users to see? (e.g., order status, payment confirmation, tracking info)"
   • Why it matters: Knowing priorities helps avoid over-designing; users need to see what matters most first
   • Follow-up triggers: For each critical field → ask "What decisions do users make based on this data?"

3. UI/UX Preferences & Constraints (Impact: Shapes storyboard style and interaction patterns)

   • Question: "Any UI preferences? (A) Web, (B) Mobile, (C) Both. And design style: (A) Minimal wireframes, (B) Detailed mockups, (C) Interact prototypes?"
   • Why it matters: Platform and fidelity affect storyboard detail; mobile has different constraints than web
   • Follow-up triggers: If (C) → ask about prototype tool; if minimal → discuss what level of detail is enough

Interview Flow

Conditional Entry:

If user has provided:
  - Existing UI patterns or references
  - AND identified critical data fields
  - AND specified storyboard detail level

Then: Skip interview, proceed directly to storyboarding

Else: Conduct interview

Phase 1: Context Assessment (Questions 1-2)

• Understand existing UI context
• Identify data priorities
• Establish storyboard scope

Phase 2: Design Guidance (Question 3)

• Determine platform and fidelity
• Adjust storyboard detail accordingly

Capturing Interview Findings

Document findings to guide storyboard creation:

## Interview Findings: [Domain Name] UI

**Existing UI Context**: [Starting from scratch / Enhancing / Matching pattern]
**Most Critical Data**: [List fields in priority order]
**Platform**: [Web / Mobile / Both]
**Storyboard Detail**: [Minimal wireframes / Detailed mockups]

**Key UI Interactions**:
- [Action 1]: [What data triggers it]
- [Action 2]: [What data triggers it]

**Storyboard Focus**:
- Prioritize showing [most critical fields]
- Ensure [specific interactions] are clear
- Reference [existing patterns] for consistency

Optional: Write to .trogonai/interviews/[timestamp]-storyboarding-events.interview.internal.trogonai.md.

---

Workflow

Given the event timeline, create UI storyboards:

1. Identify UI Screens/Views

Create a mockup for each state of the system:

Screen 1: Order Creation Form

 Place Your Order                

                                 
 Customer ID: [____________]     
                                 
 Items:                          
Product 1  Qty: [_]  Price: $_
Product 2  Qty: [_]  Price: $_
Product 3  Qty: [_]  Price: $_
                                 
 Total: $___                     
                                 
 Shipping Address:               
 [_____________________]         
 [_____________________]         
                                 
 [ Create Order ]                


Trigger: CreateOrder command
Result Events: OrderCreated
Data captured from UI:
  - customerId
  - items (products + quantities)
  - total
  - shippingAddress

2. Show State Transitions Between Screens

Document what changes when events occur:

Screen 2: Order Confirmation
(After OrderCreated event)


 Order Confirmation              

                                 
 Order ID: #12345                
 Status: Draft                   
                                 
 Items: 3 products               
 Total: $150.00                  
                                 
 Shipping: 123 Main St           
                                 
 Payment Options:                
Credit Card                   
Bank Transfer                 
                                 
 [ Confirm Order ]               


Trigger: ConfirmOrder command
Result Events: OrderConfirmed
Data from UI:
  - orderId (from OrderCreated)
  - paymentMethod

3. Document All Data Fields

For each screen, list what data is displayed:

Screen: Order Status View

 Your Order Status               

 Order ID: #12345                 (from OrderCreated)
 Status: Confirmed               (from OrderConfirmed)
 Confirmed at: 2024-12-31 10:00   (from OrderConfirmed)
                                 
 Payment: Authorized             (from PaymentAuthorized)
 Auth Code: AUTH-789              (from PaymentAuthorized)
                                 
 Inventory: Reserved             (from InventoryReserved)
 Expected Ship: 2025-01-02        (from InventoryReserved)
                                 
 Shipped: Pending                 (awaiting OrderShipped)
 Tracking: -- (waiting for shipment)


Fields and their origins:
  orderId → OrderCreated event
  status → OrderConfirmed event
  confirmedAt → OrderConfirmed event
  paymentStatus → PaymentAuthorized event
  authCode → PaymentAuthorized event
  inventoryStatus → InventoryReserved event
  expectedShip → InventoryReserved event
  tracking → OrderShipped event (when available)

4. Show Data Flow Through Screens

Map how data enters/exits UI:

Order Entry UI
   (user inputs)
   customerId
   items[]
   total
   shippingAddress
      ↓
      Command: CreateOrder
      ↓
      Event: OrderCreated
      ↓
      Order Status UI (displays)
       orderId (from event)
       items (from event)
       total (from event)
       shippingAddress (from event)

5. Organize Screens by Swimlane (Actor/System)

MANDATORY: Use the Role Catalog from Step 1 (eventmodeling-brainstorming-events) as the source of swimlanes. Every human role in the catalog MUST have its own swimlane. Every system actor that has a UI or todo-list view gets a swimlane too.

Group screens by who interacts with them:

Swimlane: Customer (Human Role)
   Screen 1: Order Entry Form
   Screen 2: Order Confirmation
   Screen 3: Order Status View
   Screen 4: Tracking View

Swimlane: Seller (Human Role)
   Screen 1: Order Fulfillment Dashboard
   Screen 2: Review Response Form
   Screen 3: Product Management

Swimlane: Support Agent (Human Role)
   Screen 1: Escalation Queue
   Screen 2: Manual Override Panel

Swimlane: Payment Processor (System Actor)
   Screen 1: Payment Verification (automated)
   Screen 2: Authorization Confirmation

Swimlane: Inventory System (System Actor)
   Screen 1: Reservation Todo List (internal)
   Screen 2: Availability Check

Swimlane: Fulfillment System (System Actor)
   Screen 1: Shipment Creation Todo
   Screen 2: Shipping Confirmation

Validation: If a role from the catalog has zero screens, either:

• The role is missing screens (add them), or
• The role doesn't belong in the catalog (remove it in Step 1)

This shows which actors interact with which screens and helps visualize system boundaries.

6. Show Processor "Todo List" Pattern

For automated processors, show the todo list metaphor:

Processor: InventoryReserver

Internal "Todo List" (based on received events):

 Inventory Reservation Todos     

                                 
Order-123: Reserve 2x Prod-1  (triggered by PaymentAuthorized)
Order-124: Reserve 3x Prod-2  (triggered by PaymentAuthorized)
Order-125: Reserve 1x Prod-3  (triggered by PaymentAuthorized)
                                 
 Processor checks todo items:    
 For each: Check availability    
          If available:  Mark done
          Reserve inventory      
          Produce event          
                                 


This todo list is driven by:
Events received → Items added to todo
Processor logic → Items processed
Success → InventoryReserved event produced + todo marked done
Failure → InventoryFailed event produced + todo marked failed

7. Identify Missing Data

Highlight where data doesn't have a clear source:

Problem: Order Status screen needs "expectedShip" date
Current state: Not in any event
Solution: Add expectedShip to InventoryReserved event

Problem: Order status needs "last updated" timestamp
Current state: No tracking of when last change occurred
Solution: Every event includes timestamp

Output Format

Present as:

# Storyboard: [Domain Name]

## Swimlane Organization (from Role Catalog)

### Human Role Swimlanes

#### Customer Swimlane
- Screen 1: Order Entry Form
- Screen 2: Order Confirmation
- Screen 3: Order Status View

#### [Other Human Role Swimlanes — one per role in the catalog]

### System Actor Swimlanes

#### Payment Processor Swimlane
- Screen 1: Payment Verification (automated)
- [Shows what UI/views the processor interacts with]

#### [Other System Actor Swimlanes]

---

## Screen 1: [Screen Name]

### Mockup

[ASCII art mockup or description]

### Data Displayed
- Field 1: Description, source event
- Field 2: Description, source event

### User Actions (Commands)
- Action: [Action], produces: [Event]

### Business Rules
- Rule about what can/cannot be done on this screen

---

## Screen 2: [Screen Name]

[Repeat for each screen]

---

## Processor Todo Lists

### Processor: [Processor Name]

Internal "Todo List" pattern:

Triggered by: [Event type] Todo action: [What needs to be done] Success produces: [Event] Failure produces: [Event]

[Repeat for each processor]

---

## Data Flow Diagram

[Show how data enters from UI and returns via events]

---

## Field Traceability Matrix

| Field | Screen | Source Event | Status |
|-------|--------|-------------|--------|
| orderId | Status View | OrderCreated |  |
| shipmentId | Status View | OrderShipped |  |
| customerId | All | OrderCreated |  |

---

## Missing Data Analysis

[Any fields without clear source or destination]

Quality Checklist

• Every screen has a mockup or clear description
• Every displayed field has a source event
• Every user action maps to a command
• Commands map to events
• Data flows make sense
• No missing data sources
• State transitions are clear
• Alternative states are shown
• Error states are shown
• Every human role from the Role Catalog has at least one swimlane
• Every swimlane is labeled with the role/actor name from the catalog
• Swimlanes organized by actor/system
• Human role screens clearly separated from processor screens
• Processor todo list pattern shown for automated systems
• System boundaries visible through swimlane organization

Key Principles

1. User-Centric: Design from what users see and do
2. Data Traceability: Every field has origin and destination
3. Completeness: All needed data is visible
4. Clarity: UI clearly shows system state
5. Consistency: Same data presented consistently across screens

Common Patterns

Input Screen Pattern

User fills form (captures command data)
  ↓
Submit button (issues command)
  ↓
Event created with form data
  ↓
Confirmation screen displayed

Status Screen Pattern

System displays current state (from read model)
  ↓
Based on latest events
  ↓
Shows all relevant information
  ↓
Available actions based on state

Error State Pattern

User action fails (command rejected)
  ↓
No event created
  ↓
Error message displayed
  ↓
UI allows retry or alternative action