Journeys

A Journey ties together an Actor, a Goal, and a sequence of Interactions into a complete user story. It's the "script" for how a user achieves their goal.

What is a Journey?

A journey answers: "How does this user accomplish their goal, step by step?"

et create journey \
  --id "checkout_flow" \
  --actor "customer" \
  --goal "complete_purchase" \
  --steps "browse_products,add_to_cart,view_cart,checkout,receive_confirmation" \
  --narrative "Customer finds products, builds their cart, completes checkout, and receives confirmation"

Journey Fields

Field	Required	Description
id	Yes	Unique identifier
actor	Yes	The protagonist (who benefits from completing this journey)
goal	Yes	The goal achieved at journey's end
steps	Yes	Comma-separated interaction IDs in order
narrative	No	Human-readable description of the flow
tags	No	Labels for filtering and organisation
meta	No	Custom key-value metadata

Creating Journeys

et create journey \
  --id "support_resolution" \
  --actor "customer" \
  --goal "get_issue_resolved" \
  --steps "submit_ticket,receive_response,provide_details,get_resolution" \
  --narrative "Customer submits issue, works with support, and gets their problem solved"

Understanding Journey Actors vs Step Actors

The journey's actor field identifies the protagonist — the person who benefits from completing the journey. However, individual steps in the journey can be performed by different actors:

# Customer is the protagonist (who benefits)
et create journey \
  --id "support_flow" \
  --actor "customer" \
  --goal "get_issue_resolved" \
  --steps "submit_ticket,support_agent_investigates,provide_solution"

# Even though "support_agent_investigates" is performed BY a support agent,
# the journey's actor is still "customer" because THEY benefit from the outcome.

This design reflects reality: the customer's goal matters most, even though achieving it requires work by multiple people.

Tags and Metadata

Tags help track documentation status, testing coverage, and journey variants.

Tracking Documentation and Testing

# Create journey with documentation status
et create journey \
  --id "checkout_flow" \
  --actor "customer" \
  --goal "complete_purchase" \
  --steps "browse,add_to_cart,checkout" \
  --tags "documented,tested"

# Mark journey as needing review
et update journey checkout_flow --add-tags "needs-review"

Tracking Journey Variants

# Tag different versions of similar journeys
et create journey \
  --id "quick_checkout" \
  --actor "customer" \
  --goal "complete_purchase" \
  --steps "quick_buy,express_checkout" \
  --tags "variant,express" \
  --meta "variant_of=checkout_flow"

et create journey \
  --id "guest_checkout" \
  --actor "customer" \
  --goal "complete_purchase" \
  --steps "browse,add_to_cart,guest_checkout" \
  --tags "variant,guest" \
  --meta "variant_of=checkout_flow"

Finding Journeys

# Find documented journeys
et list journeys --tag documented

# Find journeys needing review
et list journeys --tag needs-review

# Find all variants of a flow
et list journeys --tag variant --format json | jq '.[] | select(.meta.variant_of == "checkout_flow")'

Listing Journeys

# All journeys
et list journeys

# Journeys for a specific actor
et list journeys --actor customer

# Journeys for a specific goal
et list journeys --goal complete_purchase

# JSON format
et list journeys --format json

Viewing Journey Details

et show journey checkout_flow

Output:

ID:        checkout_flow
Actor:     customer
Goal:      complete_purchase
Steps:
  1. browse_products
  2. add_to_cart
  3. view_cart
  4. checkout
  5. receive_confirmation
Narrative: Customer finds products, builds their cart, completes checkout, and receives confirmation
Tags:      documented, tested
Created:   2024-01-15T10:30:00.000Z
Updated:   2024-01-15T10:30:00.000Z

Updating Journeys

# Add a step
et update journey checkout_flow \
  --steps "browse_products,add_to_cart,apply_coupon,view_cart,checkout,receive_confirmation"

# Update narrative
et update journey checkout_flow \
  --narrative "Updated narrative describing the flow"

# Update tags and metadata
et update journey checkout_flow --add-tags "production" --meta "last_reviewed=2024-01-15"

Removing Journeys

et remove journey old_journey

Journeys aren't referenced by other entities, so removal doesn't require --force.

The Complete Picture

A journey connects all the pieces:

┌─────────────┐     ┌──────────────────┐     ┌───────────────────┐
│    Actor    │────▶│       Goal       │◀────│    Interactions   │
│  (Customer) │     │ (Complete Order) │     │ (browse, cart...) │
└─────────────┘     └──────────────────┘     └───────────────────┘
       │                    ▲                         │
       │                    │                         │
       └────────────────────┼─────────────────────────┘
                            │
                    ┌───────────────┐
                    │    Journey    │
                    │ (Checkout     │
                    │  Flow)        │
                    └───────────────┘

Validation

Journeys are validated for:

• Actor exists: Journey must reference a valid actor
• Goal exists: Journey must reference a valid goal
• All steps exist: Every interaction ID must exist
• Goal alignment: Warning if goal doesn't belong to actor

et validate

Errors:
  ✗ [journey/checkout_flow] References non-existent interaction step 'missing_step'

Warnings:
  ! [journey/checkout_flow] Goal 'complete_purchase' is not assigned to actor 'customer'

Note: Steps can be performed by any actor. The journey's actor field represents who benefits from the outcome, not necessarily who performs every step.

Best Practices

1. One journey per goal: Each journey should achieve exactly one goal
2. Logical step order: Steps should follow natural user flow
3. Complete the story: Journey should end with goal achieved
4. Write narratives: Help humans understand the flow at a glance

Example: Multi-Journey Goal

Sometimes a goal can be achieved via different journeys:

# Same goal, different journeys
et create journey \
  --id "quick_checkout" \
  --actor "customer" \
  --goal "complete_purchase" \
  --steps "quick_buy,express_checkout,receive_confirmation" \
  --narrative "Returning customer uses saved info for fast checkout"

et create journey \
  --id "full_checkout" \
  --actor "customer" \
  --goal "complete_purchase" \
  --steps "browse_products,add_to_cart,view_cart,checkout,receive_confirmation" \
  --narrative "New customer goes through full checkout flow"

Next Steps

• Breaking Down Work: How to approach new tasks
• Validation: Ensure model integrity