State Diagram

Written as sentences, missing combinations are invisible. Three overlapping conditions make eight cases, and prose only records the ones somebody thought of. A case nobody wrote down is not absent; it is undecided, and undecided cases get settled by whoever writes the code that day.

Pagedeck hit this with invitations. The functional spec paired conditions with outcomes across about twenty lines, and as far as Mia could tell nothing was missing. Support messages arrived after launch. Clicking an expired invitation link was accepting it, and inviting the same address again after cancelling revived the earlier invitation. An invitation could be in five states, and the document only covered cases starting from three of them. Both problems were decisions the document had never made, so the code made them instead.

Reading the prose more carefully does not catch this. The missing case lives in the gap between sentences. Lay the states out as points and connect the legal moves with arrows and the squares with no arrow stay visible on the page, which is where the decision to block or allow gets made.

Pin the subject down to one thing first. An invitation, a document, a payment — the diagram only stands up once the unit that holds states is fixed.

Then there are five slots.

1. The list of states. Every shape the thing can be in. For one invitation: sent, accepted, declined, expired, cancelled. Name them so no two overlap. Put both "pending" and "unprocessed" on the page and engineering and review end up pointing at different things. Nouns work better than phrases, since the name ends up in the code and in the review checklist.
2. Transition arrows. Which state can move to which. They have direction — accepted does not go back to sent.
3. What causes each transition. Write on every arrow what produces the move. There are only three sources: a person's action, the passage of time, and a signal from another system. The arrow from sent to expired has no person on it, only the condition that seven days went by. Leave that label off and engineering has nowhere to attach the transition.
4. Start and end. Mark where things begin and which states go no further. Accepted and declined are ends; expired is not, because a re-request sends it back to sent. Marking the ends also tells review which states should be impossible to leave.
5. Conditions on shared actions. When one action leads somewhere different depending on state, the condition goes on the arrow. Clicking the invitation link goes to accepted from sent and to a re-request screen from expired.

Once it is drawn, build a grid: states down the side, actions across the top. Five states and four actions make twenty squares, and each square with no arrow gets a note about what to show there instead. Most edge cases — the rare situations that still need a defined answer — come out of exactly this pass. Twenty squares is small enough to fill in one sitting. The diagram shows the routes that exist; the grid shows the ones that don't.

The author is the person who owns the feature. At Pagedeck, Mia draws the state list and the arrows, and Noa fills in alongside her when the states surface on screen. This diagram sits at a different layer from UI state, which covers how one element looks in different situations. That an invitation is in the sent state and that its row carries a grey badge are recorded separately.

Three groups read it and each takes something different away.

1. Theo takes the stored state values and the permitted transitions. A move with no arrow is a move the code has to refuse, so the diagram doubles as the list of things to block. Anything absent is refused by default, which is a safer stance than allowing by default.
2. Noa counts how the screen looks in each state. Five states mean at least five appearances to draw, and those five get written up in the screen definition.
3. Reviewers. During quality assurance (QA), the pass that checks quality before release, someone deliberately attempts the squares with no arrow — clicking the expired link, re-inviting the cancelled address. The results land as lines in the acceptance criteria.

Drawing it once is not enough. When a state gets added mid-build, the diagram gets the addition too. A stale diagram is worse than none, because nobody doubts it and they build from it anyway.

"Draw the state diagram first. There's nothing here about what happens to expired ones."

A request to settle the missing routes between states before building.

"Does this arrow fire because someone clicked, or because time passed?"

The cause of a transition has not been written on it.

"There's no arrow from cancelled back to sent, right? Then I'm blocking that button."

Confirming that a move absent from the diagram gets refused in the code.

Pagedeck draws one only for features with more than three states. Invitations, payments, and document sharing permissions qualify; changing button copy does not. The line is drawn by how many states exist, not by how important the feature feels. Once drawing takes longer than building, the document has passed the point where it pays for itself.

Mia puts five points on a whiteboard, Theo draws arrows next to her, and two or three missing squares turn up right there. Half an hour of that against ten fewer support messages is a good trade, so the people building often ask for the session themselves.

The most common assumption is that it belongs to engineers, so the product side does not have to draw it. Arrows and boxes make it look like a technical document. But which state can move to which is a decision, not an implementation. Whether an expired invitation can be accepted is not something code should settle, and when engineering settles it by default, that decision exists only inside the code and never in writing. Six months later, nobody can answer why it behaves this way, and the cost lands on whoever inherited the feature.

The second is that splitting states finer makes the diagram more accurate. Adding points for loading and saving looks more precise, but past about fifteen points the drawing stops being readable, and a drawing nobody reads never gets updated. The test is whether the value has to be stored. That an invitation expired is stored and read back later; that something is saving right now only matters on screen for a moment. Only the first kind belongs here.