agentleFS
wilbeibiwilbeibi/wilbeibi-skills/skills/state-prototype/SKILL.md

state-prototype

Skill2 starsChanged 2 months agoMITView on GitHub

Builds a throwaway single-file HTML demo of a proposed state model, driven by an explicit transition table, with free-play buttons and scenario tabs a person can click through. Use when asked to prototype, sanity-check, or feel out a state machine, lifecycle, or status design before implementing it. Do NOT use to explain an existing mechanism (use mechanism-viz), to check every interleaving (use tla-model), to chart a checked model (use statechart), or for a static diagram (use show-me).

The file

We split this skill into the rules it gives an agent

4 rules. About 0 are common, 4 are distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈4

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 0

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Every mutable field in the state belongs to a row, and every row names one owner.

    line 22
  2. Distinctive:

    Build the page: Use one self-contained HTML file with no framework, bundler, or server.

    line 23
  3. Distinctive:

    Keep state in memory unless persistence is the question.

    line 34
  4. Distinctive:

    Write no tests and no generalisation: one prototype answers one question.

    line 35

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “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

state-prototype

A prototype is throwaway code that answers one question about a state model. The part worth keeping is its transition table.

Steps

  1. State the question (REQUIRED). Write one paragraph at the top of the page: the state model, and the one decision the demo must settle. Example: "Can a closed writer's journal reach the next writer with its old merge base?" If the question is not settled yet, run the grill-me skill first. Done when the question names one decision.
  2. Write the model as an explicit transition table in one pure <script> block, with no DOM access:
    const TRANSITIONS = [
      // from, event, to, owner: the one writer of this transition, guard
      { from: "open", event: "finish", to: "closed", owner: "runner receipt",
        guard: (s) => s.unsettled === 0 },
    ];
    function step(state, event) { /* matching row -> next state, else { refused: reason } */ }
    Every mutable field in the state belongs to a row, and every row names one owner. An event with no legal row is refused visibly, never ignored. Done when every state has an exit or is marked terminal.
  3. Build the page. Use one self-contained HTML file with no framework, bundler, or server. From top to bottom:
    • The title and the question.
    • The current state as labelled fields, with the last change highlighted.
    • One button per event, always enabled, that shows a refusal when there is one.
    • Scenario tabs. Each resets to a known start and steps through its ordered buttons.
  4. Pick scenarios from the failure cases. Cover the happy path, a failed awaited attempt, an ambiguous timeout, a crash between two steps, a late or duplicate executor, two writers at once, and a delete mid-flight. Drop a case the model cannot express, and say so on the page. Done when each scenario ends on a state the user can judge right or wrong.
  5. Hand over and capture the answer. Write the file to the OS temp directory and give its path. Never write it into the repository. When the question is settled, record the verdict and the final transition table in the design doc, issue, or code. When the table lands in code, test it table-driven, one case per row and per refused event (test-writing). Keep the HTML only if the user asks.

Rules

  • Label buttons and fields in domain words. Use code identifiers only when the reader wrote the code.
  • Keep state in memory unless persistence is the question.
  • Write no tests and no generalisation: one prototype answers one question.
  • A click-through shows one ordering. When the answer depends on timing between concurrent actors, take the question to tla-model.

Notes

  • Ported from the logic branch of mattpocock/skills prototype (MIT). Adapted: the explicit transition table with owners, failure-case scenarios, and temp-directory output.

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.