statechart

Testing tries the cases you thought of. This tries every path. The reader decides what must always be true; the checker shows whether the design can break it.

Topic: $ARGUMENTS. If that is empty, the flow in the conversation.

Do not use it for one function with no states over time. Use a test for that.

1. Write the rules first

Write each rule as one sentence the reader would agree to, such as "A customer is never charged twice". Show the rules to the reader before you trust the result. Never weaken a rule to make it hold.

2. Write the model

A model is one small Python file. Put it in .show-me/<YYYY-MM-DD>-<topic>/model.py. Read the real code or docs first; a model of a guess proves nothing.

TITLE = "Checkout With a Retry"
START = {"phase": "cart", "charged": 0}          # or a list of start states

def you_press_pay(s):
    if s["phase"] == "cart":
        return {**s, "phase": "paying"}          # None or no return: the step cannot happen

def the_charge_times_out(s):
    if s["phase"] == "paying":                   # a list: any of these can happen
        return [{**s, "phase": "retrying"}, {**s, "phase": "retrying", "charged": s["charged"] + 1}]

STEPS = {"you press pay": you_press_pay, "the charge times out": the_charge_times_out}
RULES = {"A customer is never charged twice": lambda s: s["charged"] <= 1}

def screen(s):                                   # optional: the words on each box
    return s["phase"].title()

def is_end(s):                                   # optional: states where stopping is correct
    return s["phase"] == "paid"

• Name each step as the person sees it: "you press pay", "the charge times out". Do not name the code.
• Add the things that go wrong: timeouts, retries, a second click, a crash between two writes. A model with only the happy path finds nothing.
• For things that happen at the same time, make each read and each write its own step. Every order gets tried.
• A state must hold only plain values. Keep counts small: 2 workers and 1 retry find most bugs. A model above MAX_STATES (100,000 by default) stops and says the check is not complete.
• examples/checkout.py is a working model.

3. Run it

python3 <this skill>/scripts/check_model.py model.py --out <folder>

It writes report.md, chart.json and chart.html to the folder. It exits 0 if every rule holds, 1 if there is a problem, and 2 if the check is not complete.

If a step never happened, fix the model before you trust any "holds".

Then run the page check, and read the screenshots:

python3 <show-me skill>/scripts/render.py <folder>/chart.html <folder>/shots

If the chart has more than about 20 boxes, make screen() coarser: give one word to states that the reader sees as the same. Keep each state of a bug path.

4. Replay each bug against the real thing

When the model describes code that exists, run each bug path on the real code, as a test or a live repro, one step at a time. If the bug does not happen, treat the model as wrong until you show that it is not. Then fix the real bug with /fix-it-properly, and run the checker again on the fixed model.

5. Hand over

Open chart.html, and give its full path. Never put a Mermaid chart in the chat. The terminal shows it as source code. In your reply:

• One line for each problem: the rule, and the path as numbered steps.
• Which rules hold, and the number of states checked.
• What the model leaves out. "Holds" means it holds in this model, on these counts, and nothing more.
• Whether you replayed each bug on real code, and the result.

This checks what can happen, and whether an end can still be reached. It does not check timing, speed, or that a step will ever run.