Scenarios

A Scenario declares an explicit boundary signature for one behavioral fact: a title and an ordered path of steps. Each step is either an Input — something the behavior reads, including environmental reads like a SQL query or an HTTP call — or an Output: something it writes or causes.

Each step is a structured item, not free text. Concrete values — IDs, JSON payloads, SQL, HTML — belong only in that step’s evidence, never in the step’s own summary text. This keeps a Scenario’s shape scannable at a glance while keeping every claim backed by something concrete underneath it. In the app, Inputs and Outputs are labeled Conditions and Results — same concept, the names the UI actually uses.

The path

A Scenario’s Conditions and Results are one ordered path, not two separate lists. The order is the sequence the behavior actually runs in, and a Condition sitting after a Result is legal and meaningful: it is a mid-path checkpoint that must hold at that point, not an opening precondition.

A Scenario encodes exactly one execution path. When a step forks — a charge is approved or declined, a code is valid or expired — the other outcome is a separate Scenario whose first Condition chains from the Result before the fork (see Chained). Never write the conditional as prose inside one Scenario. Several Scenarios chaining off the same Result is the fork, and each branch is published and checked on its own — which is the point.

A worked example

A Scenario titled “Checkout rejects an expired discount code” might read, in path order:

• Condition — “cart with line items and an applied discount code” (evidence: a SQL row showing the code’s expires_at in the past).
• Condition — “checkout request submitted”.
• Result — “checkout blocked with a 422 response” (evidence: the actual HTTP response body).
• Result — “discount code removed from the cart”.

The step text stays abstract on purpose — “an expired discount code,” not the literal code string or the JSON payload. That belongs in evidence, so the Scenario itself stays readable without losing anything checkable. The accepted discount code is not another branch of this Scenario; it is its own Scenario, chained from the Result before the two diverge.

Features and place

Every Scenario belongs to exactly one Feature — a named grouping (a Project’s Explore/Features views are organized by Feature). A Scenario also belongs to a place: a standing surface where someone can check the fact, named within the Project (The product, Web app, API, and so on) and classified by a closed vantage — Product, Client, or Service. Place describes perspective, not a hierarchy; nesting (see Scenario Relationships) is what encodes layers, and a nested child’s vantage must be the same as or deeper than its parent’s.

Evidence

Evidence attaches to an individual step as a concrete artifact: an HTTP response body, a SQL row, a screenshot, an HTML or JSON snippet. This is where the actual values live.

A Result can carry evidence from two sides of the same claim:

• Issued — what the system sent at this boundary: the SQL INSERT, the HTTP request, the event it published.
• Observed — what the world looks like once that landed: the stored row, the rendered page, the message in the inbox.

They are two kinds of evidence for one Result, not two Results. Either side can be left empty when you don’t know it.

Assets

An asset is supplementary context attached to a Feature or a Scenario — a note, a link, a diagram. An asset deliberately carries no status: it is background, never a checkable claim, so it can never be mistaken for the Scenario’s own evidence.

Status is separate from content

A Scenario’s two status axes — lifecycle (Draft / Published / Deprecated) and verification (Not attempted / Fit / Gap) — are plain overlays on top of the Scenario, not part of its content, and independent of each other. The path and its evidence describe what should be true; status just records whether the team stands behind it and whether reality currently lines up. See Scenario Status.

Scenarios relate to each other

A Scenario rarely stands alone. It can be nested inside a broader or narrower version of the same fact, chained to another Scenario’s Result, or share a cross-cutting concern with many other Scenarios — all at once. See Scenario Relationships.

For the practical steps of writing one, see Writing a Scenario.