In Orca (ORCA_CLI_COMMAND is set): read ../orca-harness/SKILL.md before this skill and map its Cursor names through it.

Statechart

The chart shows what an app's user sees. A PM reads it to decide whether that behavior is right. Label each state with what is on the screen, such as "Paying". Label each step with what the user does or sees happen, such as "tap Pay" or "the charge goes through". Keep variable and action names out of labels. The scripts call this user the reader, as in readerActions and reader steps.

Run node <skill dir>/scripts/statechart.mjs --help for the commands and for how to read a chart. Work in a scratch folder outside the repo. The command writes its files next to its input.

Pick the direction

Use from-spec when a TLA+ model exists or the code is concrete enough to model. Use from-chart when there is no model and the PM should agree on the behavior before anyone writes or changes the code.

If the code already has a TLA+ spec, start from a copy of that spec. Add the variables the user sees, and keep the spec's existing invariants. To audit the code against that spec, make the copy model what the code does, and pass the spec unchanged as --against. In a new spec, tie every variable and action to code that a reviewer can open, and take its name from that code. Make each action one indivisible step in the code.

Spec to chart