Journeys

A Journey is a goal where your product carries a person from one Capability into the next. Creating a document and landing in its editor, or signing up and following the emailed link to confirm, are Journeys: the Product hands the person on.

A Journey states only the goal and how you know it was met. Each concrete path is a Journey Scenario. Journeys are optional: many products have none.

In practice

When you create one

• The Product does the handing on: a redirect, a required next step, an emailed link to follow. A person merely choosing what to do next is not a Journey.
• The same person throughout. A hand-off to someone else, or a continuation the Product runs alone, such as merging once checks pass, is not one.
• At least two Capabilities. A goal one Capability meets is that Capability's Scenario, never a Journey wrapper.
• Being sent back to where you were going after signing in is not a hand-off.
• Staying where you are is not a hand-off: drafts appearing in the editor you are working in, or going back to what you were doing after creating something inline.
• An email carries only when your own action sent it. A message someone else's action or a schedule sends starts a new visit, not a Journey.

The file

journeys/<id>.md, or journeys/<id>/journey.md once it owns Scenarios. The H1 names the goal; there is no lead paragraph.

---
actors: [shopper]
---

# Browse and buy

## Goal

A shopper wants to purchase a suitable product.

## Success criterion

A confirmed order exists for the selected product.

Everything else is derived from its achieved Scenarios: the Capabilities it uses, the places it passes through, and what it leaves behind: the things those paths create, change or remove, with their final States.

Journey Scenarios

A Journey Scenario is one path through a Journey, from the person setting out to the goal achieved or not. A Scenario belongs to exactly one parent; one owned by a Capability is a Capability Scenario.

Every Journey needs at least one achieved Scenario. Add another when a condition or hand-off changes how the Journey ends. A local failure, such as a refused payment, stays a Capability Scenario too.

The Journey Scenario file

journeys/<journey-id>/scenarios/<id>.md. The ids are unique across the whole model.

---
kind: primary
result: achieved
routes:
  web: Web
steps:
  - text: The shopper finds an available product and chooses Buy
    kind: actor
    actor: shopper
    capability: browse-catalog
    entities:
      - { entity: catalog-product, effect: reads, facts: [Name and description, Price, Stock remaining] }
    contexts:
      web:
        place: customer-web::storefront::product-record
  - text: The shopper submits checkout from the product page
    kind: actor
    actor: shopper
    capability: place-order
    entities:
      - { entity: order, effect: creates, to: Pending, facts: [Items ordered, Delivery details, Subtotal, Tax, Discount, Total charged, Margin, When placed] }
      - { entity: cart, effect: removes }
    contexts:
      web:
        place: customer-web::storefront::product-record
  - text: The Product confirms the order once its payment settles
    kind: product
    actor: payment-gateway
    capability: settle-payment
    entities:
      - { entity: order, effect: changes, from: Pending, to: Confirmed, facts: [] }
    contexts:
      web:
        place: payment-webhook
---

# Browse and complete checkout

## Trigger

The shopper wants to find and purchase an available product.

## Outcome

The goal is achieved: a confirmed order exists for the selected product.

Steps and routes

Steps are written exactly as on a Capability Scenario. A Step that exercises a Capability names it in capability (the Capability, never one of its Scenarios) and happens where that Capability is offered. A Step that creates, changes or removes something must name the Capability that owns the change; a Step that only reads, or marks a transition, needs none.

The first placed Actor Step belongs to the person pursuing the goal. Routes work as on Capability Scenarios: the same Steps in different places.

Journey Scenario decision points

A decision point asks one question with at least two condition → outcome branches that keep the same Capabilities and outcome. A branch that changes either is another Journey Scenario.

How it connects

• Capabilities are named by Steps; a Journey never lists them.
• Every Capability keeps its own Capability Scenarios; a Journey Scenario never stands in for them.
• Entities change through the Steps, exactly as in Capability Scenarios.

What lint checks

Errors:

• A Journey needs an H1, no lead paragraph, actors, ## Goal and ## Success criterion, and at least one achieved Journey Scenario that includes each of its actors.
• A Journey Scenario needs kind, result, routes, steps, ## Trigger and ## Outcome, and at least one Step naming a Capability.
• An achieved Journey Scenario uses at least two different Capabilities, and carries its own Journey Actor through at least two of them; Steps of another Actor don't count.
• Each route's first placed Actor Step belongs to a Journey actor.
• A Step that creates, changes or removes something names a capability, and a Step naming one happens inside that Capability's availability.
• Every check on a Capability Scenario's Steps applies here too.

Warnings:

• A Journey or Journey Scenario id that reads as a noun phrase instead of starting with a verb, or that shortens the name of an Entity the model declares.