User flow whiteboard diagram

# User flow whiteboard diagram

Use this after a feature is defined and before development starts, so the team can review the workflow and mark it up. You draw the end-to-end user flow for a feature on an Aha! whiteboard as a swimlane diagram.

## Definitions

Use these meanings consistently in every step.

- **Feature:** The Aha! record you were given, or the record whose link or reference number appears in the chat
- **Step:** One action a person takes, drawn as a single shape
- **Decision point:** A step that branches on a choice or a condition, drawn as a diamond with one labeled path per branch
- **Swimlane:** A row grouping steps by who performs them, used when more than one role takes part in the flow
- **Column:** A vertical slot on the grid. Every shape occupies exactly one column, numbered left to right from 1.
- **Gutter:** The clear band at the top and bottom edge of each lane, reserved for connector routing. No shape sits in a gutter.

## Workflow

1. Read the feature, its requirements, and any linked ideas to understand the workflow end to end
2. Settle the scope: which flow, which roles take part, and whether alternate paths are included or only the primary path. If the feature covers distinct phases, cover the first phase only. Choose the most likely interpretation and proceed. Do not ask for confirmation unless the record cannot be read at all.
3. Identify the steps in order, from entry point to completion. Name each step as an action, such as "Select a release," not as a screen name.
4. Identify the decision points and label every branch with its condition
5. Write out the full plan in the reference table format below before drawing anything. Every shape gets a column, a lane, a shape type, a label, and a target. Keep this plan to yourself and go straight to drawing. Do not pause for approval.
6. Draw the plan on the whiteboard. Draw the lane frames and the title band first, then place shapes column by column, then connect them.
7. Add a legend and a title so the board reads on its own after the meeting ends
8. Review the finished board against the quality checks and fix what fails before returning

## Reference diagram

Match this structure. The content is a generic example. Use the roles and steps from the feature you were given, not the ones shown here.

Plan table:

```
col | lane | shape | label | connects to  
 1 | Requester | start | Start | 2  
 2 | Requester | step | Submit a request | 3  
 3 | Reviewer | step | Open the queue | 4  
 4 | System | decision | Any requests? | No -> 5, Yes -> 6  
 5 | System | end | Show empty queue | terminal, empty path  
 6 | Reviewer | step | Select a request | 7  
 7 | Reviewer | decision | Approve? | No -> 8, Yes -> 9  
 8 | Reviewer | end | Send back for edits | terminal, alternate path  
 9 | System | step | Create the record | 10  
10 | System | decision | Record created? | No -> 11, Yes -> 12  
11 | System | end | Show create error | terminal, error path  
12 | Requester | end | Request approved | terminal, primary path
```

Rendered board. Numbers are the column numbers from the plan table:

```
 ABC-123 Feature name  
 One line description of the flow.  
  
 +------------------------------------------------------------+  
Requester | (1) [2] (12) |  
 +------------------------------------------------------------+  
Reviewer | [3] [6] <7> (8) |  
 +------------------------------------------------------------+  
System | <4> (5) [9] <10> (11) |  
 +------------------------------------------------------------+  
  
 Legend: ( ) start or terminal [ ] step < > decision  
 color key for primary, alternate, empty, and error paths
```

Read four things off that sketch:

- The lane label is plain text sitting outside the lane frame on the left. It is never a shape and never overlaps the first column.
- Column 1 is always a start shape. Every branch ends in a terminal shape.
- A handoff between roles moves to the next column and drops vertically into that role's lane. Shapes never sit diagonally between columns.
- The title band sits above all lanes and the legend sits below all lanes. Neither is inside a lane.

## Layout

- Shape sizes are uniform across the board. Every step and terminal is the same size. Decision diamonds are larger than step shapes because only the inscribed square of a diamond holds text.
- Columns are evenly spaced. The gap between adjacent shapes is wide enough for a branch label to sit beside the connector rather than on it.
- Lane height fits the largest shape plus a clear gutter above and below. Add a row of height to a lane for each additional parallel row of shapes it holds.
- Center every shape vertically in its row so the gutters stay clear
- Labels cap at 20 characters for a step shape and 16 for a diamond, wrapping to two lines maximum. Shorten the label rather than growing the shape.
- One shape per column. Every shape sits inside a lane, terminal states included.
- Lanes are ordered by who acts first, top to bottom, with the human role in the top lane

## Routing

- Connectors are orthogonal only: horizontal within a lane, vertical between lanes. No diagonals.
- No connector passes through a shape. Leave clear space around every shape.
- No two connectors share a path. When two connectors run the same direction between the same two points, offset the second. If a third is needed, widen that lane's gutter rather than stacking them.
- Connect adjacent columns directly. A connector that spans more than two columns, or that returns to an earlier column, routes through the nearest gutter rather than across the middle of a lane.
- Each branch out of a decision point leaves from its own side of the diamond. Two branches never leave from the same edge.
- Branch labels sit on the connector close to the diamond they leave. Never place a label in open canvas, and never stack two branch labels at the same height.
- Arrowheads point at the target shape, never back at the source

## Rules

- One diagram covers one flow: 12 columns maximum, 3 lanes maximum, 4 decision points maximum. If the feature has phases or paths this diagram does not cover, name them in the written summary and offer to draw them as a second board.
- The flow starts with a start shape and every path ends at a terminal state. A path that stops mid-flow is an unfinished diagram.
- Include the error path and the empty path, colored distinctly from the primary path. If the feature has neither, say so in the written summary rather than leaving them out silently.
- Label every branch out of a decision point
- Keep step names to a short action phrase rather than a sentence
- Name lanes after the roles in the feature, using the terminology the record uses
- Reference the feature by reference number and name
- Build the diagram on the whiteboard and stop there. Do not create or update any Aha! records from the shapes.
- Run end to end without checking in. Ask a question only when the record cannot be read at all. Anything you would otherwise ask becomes an open question in the written summary.

## Output

A whiteboard diagram containing:

- Title and a one-line description of the flow, in a band above the lanes
- Start shape, ordered step shapes, decision diamonds with labeled branches, and terminal shapes, all on the grid
- Swimlanes when more than one role takes part, each labeled outside the lane frame
- Error and empty paths, visually distinct from the primary path
- A legend below the lanes explaining the shapes and colors

Follow the diagram with a short written summary of the flow and the open questions it surfaced, plus any phase or path left for a second board.

## Quality checks

Run every check and fix what fails before returning.

- Column 1 holds a start shape
- Every path reaches a terminal state
- Error and empty paths are present and visually distinct
- Every branch out of a decision point is labeled, and every arrowhead points at its target
- Step names are actions rather than screen names
- No two shapes overlap, and every lane label sits outside its lane frame
- Every shape sits inside a lane, and every gutter is clear of shapes
- Every connector is horizontal or vertical, passes through no shape, and shares no path with another connector
- Labels fit inside their shapes at the stated character caps
- Column spacing is even across the board
- Title and legend sit outside the lanes