agentleFS
alexderzalexderz/agentic-toolbox/skills/statechart/SKILL.md

statechart

Skill5 starsChanged yesterdayMITView on GitHub

use this when charting how a system or a user flow moves between states, in the reader's words — draw a Mermaid stateDiagram-v2 from a TLC-checked TLA+ model and report each broken rule as its shortest path, or chart a user flow from approved stories, labelled "not model-checked" when no checked model backs it.

29 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use ketchup-video, show-me and 1 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • tristanphvnSkill

    ketchup-video

    Catch the user up like /keel:ketchup, with a short silent video of slides for what happened and the waiting calls as text under it. Use for /keel:ketchup-video.

    Also in 10 projects that use this

  • AnasX7Skill

    show-me

    Help the user understand the current topic visually with concise diagrams, code-shape sketches, and focused HTML artifacts.

    Also in 3 projects that use this

  • SentrySkill

    deslop

    Strip AI-generated noise from the diff before pushing — extra comments a human wouldn't write, defensive try/catch in trusted code paths, casts to any, inline imports in Python, and other style inconsistencies with the surrounding file. Use this immediately before commit so the diff stays clean.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

25 rules. 0 are common, 13 are distinctive, and 12 are very specific to this project.

  • 0

    Common

    Most of the 28 edited versions we read keep these.

  • 13

    Distinctive

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  • could be automatic: a setting could enforce it
  1. Distinctive:

    Never weaken a reader rule to make it hold: When no variable can express a rule, add one to the model.

    line 26
  2. Distinctive:

    Run TLC from the TLA+ tools the product repo already uses.

    line 39
  3. Distinctive:

    Ask the operator only per Asking the operator.

    line 45
  4. Very specific:

    Write each reader rule as an INVARIANT in the config.

    line 60
  5. Very specific:

    Write Next as a disjunction of named actions, such as YouPressPlay \/ YouPressStop.

    line 61
  6. Very specific:

    Keep the constants small, or add a CONSTRAINT, so the state space is finite.

    line 68
  7. Very specific:

    Run TLC once on the unmodified config with -workers 1 -dump dot,actionlabels <file>.

    line 72
  8. Very specific:

    Keep the output as tlc.out.

    line 73
  9. Very specific:

    If TLC reports a broken invariant, a broken PROPERTY or a deadlock, save its trace as that rule's bug path, in tlc-<rule>.out.

    line 74
  10. Very specific:

    Remove that rule from the working copy of the config, keeping earlier removals.

    line 78
  11. Very specific:

    Keep the .dot graph and the distinct state count from the last run.

    line 82
  12. Very specific:

    If the last run finished with no error, it explored every reachable state inside any CONSTRAINT.

    line 83
  13. Distinctive:

    If a run stops on an error or does not finish, list each rule it did not check under "Rules not checked".

    line 85
  14. Distinctive:

    Read these limits before you trust a result:

    line 89
  15. Distinctive:

    Write a table: each model state, or each group of variable values, to one chart state label.

    line 99
  16. Distinctive:

    Write a table: each TLC action to one step label, in the reader's words.

    line 106
  17. Very specific:

    If a step is possible only in some situations, append that situation in square brackets, phrased for the reader, as in you tap pay [while …

    line 109
  18. Distinctive:

    When a hidden value picks the step's destination, put the outcome in the label, as in "the stock lookup fails".

    line 114
  19. Distinctive:

    If the distinct state count kept in Run TLC step 5 is above 500, draw only the bug paths.

    line 121
  20. Very specific:

    Never merge two states that break different rules.

    line 130
  21. Distinctive:

    If it is still too busy, hide steps the reader can skip, such as a reset available everywhere or an arrow that duplicates others.

    line 133
  22. Distinctive:

    Add the class lines and a Legend.

    line 143
  23. Very specific:

    Put a title on the chart with Mermaid front matter title:.

    line 156
  24. Distinctive:

    When the model describes code, re-run each bug path on the real code, as a test or a live reproduction, one code step per model action.

    line 165
  25. Distinctive:

    If no TLC run backs the chart, put "not model-checked" in its title and in the handoff.

    line 181

“Common” is measured: kept by at least 6 in 10 of the 28 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Statechart

Rewrite of cursor/plugins pstack/skills/statechart @ 3dbd22ff12742fb28c9700b9760baa29ed41dc13 (MIT), method only. Compress, not a paste. Pin: SOURCES.md.

A statechart draws the states a system passes through and the steps between them, labelled for the reader, who judges whether the behavior is right. The deliverable is plain Mermaid stateDiagram-v2 text, written by hand. Rendering it is optional.

Names

  • Reader — whoever decides whether the charted behavior is right: the operator, or someone the operator names in writing.
  • Reader rule — one rule the reader agrees to, in the reader's words, such as "you are never charged twice". It may concern what a screen shows, an outcome, saved data or a sent message.
  • Model state — one state TLC reports: one value for every variable.
  • Chart state — one box in the chart, labelled in the reader's words. Several model states can share one chart state.
  • Step label — the words on an arrow: the event as the reader would describe it, such as "you tap pay" or "the card is declined".
  • Bug path — TLC's shortest trace from a start state to a state that breaks one reader rule.
  • Mark — the class breaks on a chart state where every model state behind it breaks a rule, or mayBreak where only some do.

Iron law

Never weaken a reader rule to make it hold. When no variable can express a rule, add one to the model. If a rule breaks, report its bug path instead. A chart drawn without a checked model is labelled "not model-checked" in its title and in the handoff.

Actors

  • architect or verifier: charts a TLA+ model and reads TLC's results.
  • builder: reads TLC results while following a verify skill.
  • designer: charts a user flow from approved stories.

Toolbox policies

  1. Run TLC from the TLA+ tools the product repo already uses. Adding TLA+ tools to a product repo follows formal-verification Toolbox policies step 3.
  2. Work in a scratch folder outside the repo. When a verify skill keeps the spec in the repo, read the spec there and write every TLC output and chart to the scratch folder.
  3. Ask the operator only per Asking the operator.
  4. The upstream pstack statechart command is an operator opt-in, used only when the operator says so in writing, at the operator's own risk. It is TypeScript at cursor/plugins pstack at 3dbd22f. It needs mise and a TypeScript runtime already installed; its first run installs Java and TLC into the user's mise store and needs the network. This toolbox does not vendor it, run it or give an install command for it. Without that opt-in, follow this file.

Chart a checked model

The architect, verifier or builder uses this section.

Write the spec

  1. Write each reader rule as an INVARIANT in the config. Name it after the rule.
  2. Write Next as a disjunction of named actions, such as YouPressPlay \/ YouPressStop. Without names, every step is Next.
  3. For each correct end state, add one action to Next that is true only in end states and leaves every variable as it is, for example Finished == stage \in {"shipped", "cancelled"} /\ UNCHANGED vars. TLC reports any state with no step out as a deadlock, a correct end state included; once those actions exist, every deadlock TLC reports is a bug.
  4. Keep the constants small, or add a CONSTRAINT, so the state space is finite.

Run TLC

  1. Run TLC once on the unmodified config with -workers 1 -dump dot,actionlabels <file>. Keep the output as tlc.out.
  2. If TLC reports a broken invariant, a broken PROPERTY or a deadlock, save its trace as that rule's bug path, in tlc-<rule>.out. TLC stops at the first break; for an invariant or a deadlock its trace is the shortest path to it.
  3. Remove that rule from the working copy of the config, keeping earlier removals; for a deadlock, set CHECK_DEADLOCK FALSE. Rerun TLC on the working copy with the same flags.
  4. Repeat steps 2 and 3 until no rule breaks.
  5. Keep the .dot graph and the distinct state count from the last run. If the last run finished with no error, it explored every reachable state inside any CONSTRAINT; otherwise apply step 6.
  6. If a run stops on an error or does not finish, list each rule it did not check under "Rules not checked". Do not mark those rules. A rule not checked can hold or break.

Read these limits before you trust a result:

  • A state beyond a CONSTRAINT or ACTION_CONSTRAINT still has its reader rules checked, but TLC neither expands it nor tests it for deadlock, so a deadlock there stays hidden.
  • A VIEW or SYMMETRY makes TLC fold equivalent states into one. An arrow can lead to that one state rather than to the state the step reaches. Say so in the report.

Map states and steps

  1. Write a table: each model state, or each group of variable values, to one chart state label. Use what the reader sees or cares about, such as "Checking out" or "Lock taken, save not yet written", never a variable name. The label is a function of the model state alone.
  2. Choose the form. Flat: one label per state. Nested: a parent state holds child states, written as state "Parent" as p { ... }. Parallel: one region per independent part, separated by -- inside a parent state.
  3. Write a table: each TLC action to one step label, in the reader's words. Never name the code or the TLA+ action. Actions that land the same way in the chart get one shared label, and so one arrow.
  4. If a step is possible only in some situations, append that situation in square brackets, phrased for the reader, as in you tap pay [while the cart is saving]. In a parallel chart, never bracket a condition on another region; write that region's label, such as [when Offline].
  5. When a hidden value picks the step's destination, put the outcome in the label, as in "the stock lookup fails".
  6. A step that stays inside one chart state draws no arrow. If the reader must see that step, split the label.

Draw the chart

  1. If the distinct state count kept in Run TLC step 5 is above 500, draw only the bug paths; if no rule broke, draw no chart, report the state count, and say that a smaller model is needed to see the graph. Otherwise draw every chart state reachable from a start state, and every arrow.
  2. Count the arrows. Above about 20, coarsen first: merge values that behave alike under one label, and drop detail the reader can skip, such as a pending call whose answer changes nothing.
  3. While coarsening, keep every state of every bug path and every mark. Never merge two states that break different rules; keep them as separate chart states. A merge that turns breaks into mayBreak hides where a rule breaks; undo it.
  4. If it is still too busy, hide steps the reader can skip, such as a reset available everywhere or an arrow that duplicates others. Hide every step behind an arrow, or none. Every chart state must stay reachable from a start state. A chart state that can move in the model keeps at least one outgoing arrow.
  5. Mark broken invariants by their values in the graph's state labels: breaks if every model state behind a chart state breaks one, mayBreak if only some do. Mark a deadlock on each graph state with no outgoing edge. A broken PROPERTY gets its bug path only, no mark. The graph explored past each broken rule, so states after a bug appear too.
  6. Add the class lines and a Legend. One Legend state per mark names the rules it marks; if two rules break in one state, name both:

    stateDiagram-v2
      classDef breaks fill:#ffecee,stroke:#e72e3b,color:#cd2834
      classDef mayBreak fill:#fff3e6,stroke:#e8730c,color:#b85a06
      state "Breaks rule: never charged twice" as legend_breaks
      class legend_breaks breaks
  7. To color phases, give each phase a classDef and a class line. A chart state whose model states are in different phases gets no phase color.
  8. Put a title on the chart with Mermaid front matter title:.

Report and replay

  1. For each broken rule, write: the rule's name, the reader's sentence for it, and its bug path as numbered steps in step labels.
  2. Say which chart state breaks which rule.
  3. List "Rules not checked", if any, and the steps the chart hides.
  4. Say what the model leaves out.
  5. When the model describes code, re-run each bug path on the real code, as a test or a live reproduction, one code step per model action. If a bug does not occur, treat the model as wrong until you show it is not.
  6. Hand off the Mermaid text in a mermaid code block, the report, and the TLC commands that make the files again into a new scratch folder.

Chart a user flow

The designer uses this section for the product's most important user flows.

  1. Take the flow from stories the operator approved in ux-design.
  2. Name the reader rules the stories promise, in the reader's words.
  3. Map each screen or state the user sees to a chart state, and each user action or system event to a step label, per Map states and steps steps 1–6.
  4. Draw it per Draw the chart steps 2, 4, 7 and 8. Without a checked model, draw no mark.
  5. If no TLC run backs the chart, put "not model-checked" in its title and in the handoff.
  6. To check the flow, write it as a spec with the reader rules as invariants and follow Chart a checked model.
  7. Hand off the Mermaid text in a mermaid code block, the stories it came from, and whether it is model-checked.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.