# How to review a state machine before your agent writes the code

Our /design-docs skill shows a person the state machine before any code exists. What it asks for, what a Quint check found in our trials, and where it did not pay.

If your agent draws the state machine after it writes the code, the diagram can only tell you what the code already does. You find a wrong turn once it is built in. Put the machine first, as a design you accept or reject, and a wrong turn costs you one rejected line. This post shows how we do that, what it found, and where it was not worth the time.

Matthew Phillips, co-creator of Astro, wrote on Nov 9: "Finite state machines are an incredible abstraction for the agentic era. Don't read the code but still need to understand the architecture." Understanding the architecture without reading the code is the job our `/design-docs` skill does. It is public, and you can [read the whole text](https://github.com/mbsi-labs/skills/tree/main/plugins/design-docs/skills/design-docs).

## You are asking for the machine too late

The skill fixes the order in one line: "this kind of ask ⇒ these types ⇒ these functions". The machine sits between the ask and the functions, so a person can see it before any function exists.

The default design, which the skill calls bronze, has "Five parts, in this order, and nothing else": the ticket, the proposed types, the state machine, the assumptions, and a note on what else the build serves. The person reviewing "mostly reads the assumptions", so the skill says to "write the smallest design that lets them do that."

## Write the machine as types, and put the interruptions in it

The skill's rules for the machine are short. "Put a module's states in one union type, with each state its own variant carrying only its own fields." "Put its events in a different union type." "Write one transition function. It takes a state and an event and gives the next state and the effects." And: "A surface does not make decisions." A surface is a command, a route or a page. So every decision sits in the transition function, and that is the one place you look.

Here are the events from a model we wrote for one of our own agent skills, the checklist an agent follows before it hands a ticket back (the states are left out). In our run the reviewer was Kestrel, an agent that reviews other agents' work.

```ts
type Event =
  | { kind: "ProveAsk"; ask: number }
  | { kind: "AddAsk"; ask: number }       // the person amends the ask mid-ticket
  | { kind: "AskReviewer" }
  | { kind: "ReviewerReply" }
  | { kind: "WriteNotes" }
  | { kind: "Land" }
  | { kind: "Handback" }
  | { kind: "ReopenAfterReview" };
```

`AddAsk` is the kind of event a happy path leaves out. For anything with behavior over time, the skill's silver tier asks for "every actor and every interruption the ask allows (crash, context clear, timeout, a second writer)". An interruption you did not write down is one the machine cannot check.

## Review the assumptions, not the picture

A diagram shows states. It does not show which choices were the agent's. So the skill keeps the assumptions as their own list, "Each one acceptable or rejectable on its own, none contradicting another", and it puts every choice the person "might make differently" there, "including choices about what is left out." The person's answers "go on the ticket verbatim".

The skill also turns the list into a score: "the count of wrong ones per author is a measure to drive to zero." A wrong assumption is one you rejected, and a rejection is cheap before the code exists.

## Check the machine before any code exists

You can go one step further than reading. The silver tier says to model-check the state machines in Quint, an open-source tool from Informal Systems. You write the machine as a model, state what must always hold, and `quint run` and `quint verify` search for a sequence of events that breaks it. The skill says: "List each bad trace in plain words as a flaw in the design, with the change it calls for, or as a mistake in the model."

We wanted to know whether this earns its place, so we ran a test. We gave Opus 5.5 the original ask for our ticket-claim tracking, the part of our system that records which agent holds which ticket, the problem part of our plan for it, our success measures and some neutral facts about the world, plus the Quint docs. It had no access to our code. Mackenzie Bowes, who runs our shop, set the bar before the results came in: "at least two failures". The model's findings were then checked against bugs we had hit later.

| What the model found | The real bug it matched |
|---|---|
| A handback leaves no claim, so reviewer replies are refused | Handback dropped the claim and blocked replies to the reviewer (exact) |
| Claims are keyed by session id, so a nap or `/clear` looks like death | Claims not held after a clear (exact) |
| An idle stop cannot be cleared by writing why not | Paused tickets triggering idle stops (partial) |

It made eight findings in all. Five counted: the three above, plus two new ones we confirmed in the live code. The other three did not. The run took about 24 minutes and cost $2.91: $2.53 for the first run, which a 4 GB memory cap killed, and $0.38 to resume it and write the report.

## Know where the check stops paying

Where it did not pay is as useful. Our first trial was the handback checklist above. We started it because a page had shipped with two of the items we asked for missing. The model showed that the checklist as written lets an agent hand back with an unmet ask. Then it showed that our proposed fix, a ledger of asks, was also incomplete: a fix made after review was never reviewed again. It took about seven minutes. Keel, the agent who ran it, wrote: "It did not find a bug I could not have found by thinking about 'fix after review', but it forced the state list and the stale-proof rule to be explicit and caught that my own proposed fix was incomplete."

The second trial was land, our tool for landing a change in a shared repository. Land's core is already one pure step function from state and event to the next state, which is the shape the skill asks for. The model found no bug. Remove land's guard against installing an older build over a newer one and it finds a counterexample in 6 steps. With the guard, it found none in 13 seconds. Rowan, the lead agent who reviewed both trials, put it this way: "Quint for multi-writer processes with no pure core; marginal elsewhere."

One limit holds for both. "Quint checks the DESIGN of the process, not whether an agent follows it." The missed items were an agent skipping a step, which no model prevents. The model tells you which guard to enforce.

## The rule

Read the machine, and read it first. The skill is at github.com/mbsi-labs/skills, in `plugins/design-docs/skills/design-docs`. You can skip reading the code, but only if you read the machine before the agent writes it.

If you're running agents off state machines, I'd like to compare notes: **mackenzie@mackenziebowes.com** or **@\_mackenziebowes**.

---

Published 2026-11-09. Web page: https://www.mackenziebowes.com/posts/how-to-review-a-state-machine-before-your-agent-writes
