# User Flow Specification

Turns a task and a system's real capabilities into a flow a developer can build — including every state that is usually left undrawn.

## Deliverable

One Markdown document, `user-flow-specification.md`, in the structure set out under **Output** below. It is the input to **Interface Copy Specification** and the reference that **Usability Review** walks against.

## Required inputs

- **The task the user must complete** — stated as an outcome the user would recognise, not as a screen they should see.
- **What the system can actually do on that path** — the operations available, what each one requires, and what it refuses.
- **A named owner for undefined behaviour** — the person who decides what happens in a state nobody has specified.

If any of the three is absent, stop and report it. A flow drawn without the system's real capabilities specifies a product that does not exist.

## Optional inputs

- Existing screens, wireframes or a built interface to read the current path from
- The permission model: who may do what, and what happens when they may not
- The error and status responses the system returns, with the conditions that trigger them
- Support records or analytics showing where attempts currently stop
- Content, legal or regulatory constraints on what a step may ask for or say
- The devices, input methods and connection conditions the flow must work under

Every absent optional input becomes an entry under **Undefined states**. It never becomes an invented behaviour.

## Execution

**1 — Fix the boundaries.** Record every entry point into the flow — where the user arrives from and what they already know on arrival — and every exit: completion, abandonment, and being thrown out by the system. An entry point that cannot be named is an entry point nobody has designed for.

**2 — Walk the successful path.** One line per screen or state, in order: what the user sees, what they can do there, what the system does in response, and what changes as a result. Take it only from the supplied material; a step nobody described is a step that goes on the missing list.

**3 — Mark the decision points.** For each branch: what is decided there, the condition that determines it, and where each outcome leads. A branch whose condition was not supplied is recorded `condition unknown` and carried forward.

**4 — Specify the states for every step.** Empty, loading, error, permission-denied and partial-success, step by step. Each is either specified or marked `cannot occur` with the reason it cannot. A step that carries none of the five has not been examined.

**5 — Trace the return paths.** Going back, reloading, arriving mid-flow from a link, resuming an abandoned attempt, returning after a timeout, and running the flow twice. Record what the system does with work already in progress.

**6 — Name the undefined.** Every state reached in steps 2 to 5 with no defined behaviour, each with who must decide it and what it blocks. This list is the deliverable's main value; do not shorten it by choosing a behaviour.

**7 — Record what the flow depends on.** The system operations, permissions, content and data each step needs, and which of those were confirmed rather than assumed.

## Output

`user-flow-specification.md`, in this order:

- **1. Task and date** — the task this flow completes, and when it was specified
- **2. Entry points and exits** — per entry: where the user arrives from and what they know; per exit: how the flow ends
- **3. Steps** — per step: what the user sees, what they can do, what the system does, what changes
- **4. Decision points** — the branch, the condition that determines it, and the destination of each outcome
- **5. States** — per step: empty, loading, error, permission-denied, partial success; each specified or marked `cannot occur` with its reason
- **6. Return and re-entry** — back, reload, mid-flow arrival, resumption, timeout, repeat
- **7. Undefined states** — the state, who must decide it, what it blocks
- **8. Dependencies** — what each step needs from the system, from content and from data, marked `confirmed` or `assumed`
- **9. Missing information** — what could not be specified, and who can supply it

## Validation

The specification is ready when all of these hold:

- Every step in section 3 has an entry for all five states in section 5
- Every state in section 5 is specified or marked `cannot occur` with a reason
- Every branch in section 4 names its condition and a destination for each outcome
- Every path leads to an exit in section 2 or to an entry in section 7
- No step specifies an operation the supplied capabilities do not include
- Section 7 is either non-empty or states explicitly that nothing is undefined

Fail the run if a step is missing a state entry, or if the flow specifies behaviour the system was never reported to have.

## Failure handling

- **No task supplied** — stop. Report that a flow has nothing to sequence, and that a screen list is not a task.
- **System capabilities unknown** — specify the flow from the material supplied, mark every step `unverified`, and list in section 9 what confirming them would settle. A flow resting on assumed capabilities is a proposal.
- **Contradictory accounts of a step** — record both, name both sources, and raise the contradiction in section 9 as blocking. Do not resolve it by choosing.
- **No access to the built interface** — section 3 is `reported` only. State that nothing was observed, and that every state in section 5 is therefore a specification rather than a description.
- **Partial material** — specify every step the material supports, mark the rest `INCOMPLETE — pending <question>`, and deliver. The undefined list is the point of the document, not a defect in it.