Writing a Scenario

A Scenario is one behavioral fact: a Title and an ordered Path of Conditions (Inputs) and Results (Outputs), each optionally backed by evidence. Everything is filled in through the in-app editor — there’s no file to write and nothing to import. See Scenarios for the concept this page walks through in practice.

Opening the editor

Click New scenario to start one from scratch, or Edit content on an existing Scenario. Both use the same editor: an Identity section (the title, the Place the Scenario is written from, and — when creating one — the Feature it belongs to), a Relationships section with the pickers covered in Relating Scenarios, and a Signature section holding the Path. Creating one is a single page and a single submit — there’s no separate step to add its steps afterward.

The Path

Conditions and Results share one ordered path, in the order the behavior actually runs. Click Add condition or Add result to append a step, then describe it in the text box; drag a step to reorder it.

Conditions are every read the behavior depends on — including environmental reads like a database query or an incoming HTTP request, not just obvious user input. Results are every write or effect it produces. A Condition placed after a Result is a mid-path checkpoint that must hold at that point, and the editor marks it as one.

Keep step text abstract — “cart with an expired discount code,” not the literal discount code or the JSON payload. Concrete values belong in evidence, one level down.

One path per Scenario

A Scenario describes exactly one execution path. When a step forks, write the other outcome as its own Scenario chained from the Result before the fork — never as an “if/otherwise” inside one step’s text. The editor watches for this: a step that smuggles in a conditional, or a Result naming both sides of an outcome (“approved or declined”), raises a hint with an add outcome action that starts the sibling Scenario for you, sharing the opening steps you pick.

Adding evidence

On any step, click Add under Evidence to attach a concrete artifact. Pick a type — HTML, JSON, HTTP (request and response, one block each), SQL (a query and its result rows), Image, Markdown, or plain Text — and paste the content. This is where IDs, request/response payloads, SQL, and HTML snippets belong. Strong Scenarios ground every claim in an artifact like this, not in abstract intent.

On a Result, evidence can be marked Issued (what the system sent — the INSERT, the request, the published event) or Observed (what the world looks like afterwards — the stored row, the rendered page). They’re two sides of the same claim, not two Results, and either side can be left empty when you don’t know it.

What’s not part of a Scenario

Neither status axis is set from this editor. Every new Scenario starts as a Draft with verification not attempted, and both are changed separately, from Explore or the Scenarios list — see Managing Status. A Scenario whose verification is a gap also gets a plain Drift note text box on the edit page, for describing what actually happens instead.

Saving

Click Save. See Editing & Saving for what happens next — including how conflicting edits are handled.