Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Design

The skills in this chapter settle the shape of a change before code commits you to one. A single attempt at a hard design tends to lock in the first shape the model thought of, and discovering the mistake after implementation is far more expensive than resolving it beforehand.

The chapter covers 3 skills:

  • /architect sketches types, signatures, and module boundaries;
  • /statechart model-checks a system that moves between states and draws it for the person who owns the behavior;
  • /arena runs several independent attempts at the same task and merges the best parts.

Two related skills live elsewhere. /interrogate, which asks adversaries to break a finished design or change, is in Understanding and Investigation. /swarm, which fans workers out across independent slices or races and aggregates their reports, is in Operations and Automation; unlike /arena, it gives each worker a different scope and does not pick a base or graft.

/architect: sketch the shape before you code

Source

  • What it does: before any code is written, it traces every system the change touches and then sketches 2 different shapes for the change, each expressed as types, function signatures, and module boundaries. According to its description, it then stays in the loop while the implementation fills in the chosen shape.
  • When to use it: non-trivial work that crosses function boundaries, where starting with code would fix the wrong shape in place. Typical triggers are /architect, “architect this”, and “design this”.
  • How it proceeds: it compares the 2 sketches against 3 criteria and keeps the one that does best.
    • Each piece of state has exactly one owner.
    • Each task has exactly one way to be done.
    • Callers need to know as little as possible.
  • Caveats: when one workaround keeps coming back during implementation, the skill revisits the design rather than patching around it. A large or disputed design goes to /arena instead of being sketched by a single agent. To review the design yourself before any code is written, state that in the prompt.

The guide gives this example: /architect design the import pipeline before writing any code. i care most about how callers use it. It adds that /poteto-mode already calls /architect on its own for work that crosses boundaries; a direct call is mostly useful when you want a level of scrutiny above or below the default.

/statechart: check a state machine and show it in the reader’s words

Source

  • What it does: given a TLA+ model of something that passes through states (a product flow, a protocol, or a service), it runs the TLC model checker and renders the outcome as a Mermaid statechart. For every state that violates a rule, the report shows the shortest path leading there. The skill refers to whoever reads the chart as the reader, and it is the reader who judges whether the behavior is correct.
  • When to use it: when someone who owns a behavior needs to see it instead of reading a specification, or when you want to present a bug as a path through states.
  • How it proceeds:
    1. Write a TLA+ spec and its config in a scratch folder outside the repository. Every rule the reader agrees to becomes an INVARIANT, and if the model has no variable for a rule, you add one. A rule is never weakened to make it hold. Next should be written as a disjunction of named actions, otherwise TLC labels every step Next. Because a state with no outgoing step breaks NoDeadlock, even a correct end state needs an explicit action that is true only there and changes nothing.
    2. Run the bundled command: <skill dir>/scripts/statechart SPEC.tla [--config FILE] [--view FILE] [--out DIR]. The script is TypeScript, so it needs a runtime that can execute TypeScript, and the first run installs TLC and Java with mise, which requires network access.
    3. Write a view module, passed with --view, that carries the judgment calls. Its state(vars) function maps model values to the reader’s labels; returning a string gives a flat chart, an array gives nested parent states, and an object gives one parallel region per key. Its optional step(action, from, to) labels each arrow as the user experiences it, such as “you press play”, with conditions in brackets. Optional group, colors, and title exports set phases, colors, and a heading.
    4. Show chart.mmd to the user as a mermaid code block, rendering it with the Pele package when an image is needed.
    5. Hand off the chart and its Mermaid text to the person who must decide, with one line per bug: the rule, the reader’s sentence for that rule, and the numbered path from the report. Say what the model leaves out, and give the command that regenerates the files.
  • Keeping the chart readable: labels use what the reader can see or cares about (“Paying”, “Lease held, write pending”) and never variable or action names. The target is about 20 arrows or fewer, reached first by coarser labels and then, if necessary, by returning null from step() for steps the reader does not need. States on a bug path must stay, and 2 states that break different rules must never be merged, because the reader would no longer see which rule breaks where. Hidden steps must keep every chart state reachable, and the hand-off must say which steps are hidden.
  • Reading the report: a state that breaks a rule is marked breaks, and one where only some underlying model states break it is marked mayBreak. Because TLC continues past a violating state, the chart also shows what happens after a bug. The command checks the config as written; each time a rule breaks, it removes that rule and runs TLC again, and after the first break each run stops at 100,000 distinct states. Rules left unchecked by that bound or by an error appear under “Rules not checked”, and they may hold or break.
  • Caveats: a model without a limit on its states can run without end, so keep constants small or add a CONSTRAINT. The chart has a budget of 500 states; above it, only the paths to broken rules are drawn, and if nothing breaks, no chart.mmd is written at all. When the model describes real code, each bug path must be replayed against that code as a test or a live repro, one step per action. If the bug does not occur, assume the model is wrong until you show otherwise.

/arena: several attempts, one merged result

Source

  • What it does: it spawns N candidates that attempt the same task in parallel, picks one result as the base, and grafts the strongest parts of the other candidates into it. This guards against a single attempt locking in the wrong shape for a non-trivial artifact.

  • When to use it: designs, code, documents, and standalone decisions such as names, formats, or algorithms, where the first shape is costly to change later. Triggers include /arena, “arena this”, and “throw it in the arena”. /architect also calls it for large or contested designs.

  • How it proceeds: it first opens a todo list with one entry per phase.

    PhaseWhat happens
    A. FrameAll candidates get an identical prompt, which therefore serves as the contract. Name the artifact, then work out a rubric of 3 to 6 concrete criteria for this task that can be graded; the rubric is shown to the picker only. Take the runners from the arena runners line in the model configuration (by default claude-fable-5-2-high, claude-opus-5-5-high-fast, and gemini-4-neon-high), and assign every candidate a separate output location: a git worktree if possible, and /tmp/arena-<slug>/candidate-<n>/ if not.
    B. Fan outLaunch all candidates in one message, in the background. Each produces the artifact plus a short rationale naming the alternatives it considered and rejected. If one produces nothing, continue with the rest and record the dropout.
    C. Cross-judgeSpawn one read-only judge from the arena cross-judge pool line, never from the parent model’s vendor (Fable counts as Claude for this check). The judge scores each candidate, identified only by its path label, on every rubric criterion and recommends a base.
    D. Pick a baseRead every candidate end to end and score it criterion by criterion, not on overall impression. Agreement with the judge confirms the pick; disagreement means bias on one side or an ambiguous rubric, so both rationales are reread. The base is the one a future maintainer can extend most easily without breaking invariants, and a tie goes to the cleaner boundary or the smaller API.
    E. GraftWalk each losing candidate once more for the 1 or 2 ideas worth porting, and fold each one in by hand so the result stays coherent under one mental model.
    F. VerifyVerify the merged artifact like any other output. A problem found here means either the framing was wrong (reframe and rerun) or a candidate had caught it and the graft was missed (return to Phase E).
  • Output: one merged artifact with a short synthesis note that names the base and the reason, the judge’s verdict or the fact that the judge was skipped, the source of each graft, what was rejected and why, any convergence or dropouts, and the verification result.

  • Caveats: if the candidates converge on one shape, that is strong agreement, and the consensus ships without grafts. If they diverge wildly, Phase A was under-specified, and the right response is to reframe and rerun instead of averaging the divergence. Runner fallbacks are explicit: an unavailable model is replaced by the nearest valid slug of the same family or dropped, at least 2 runners must remain, and the agent says what it changed. You can ask for more candidates when a decision matters, and the skill allows repeating one model when the work is bound by generation volume rather than judgment.

The runner panel comes from your /setup-pstack configuration and can be adjusted per task, for example /arena this, 5 candidates. the cache key format is expensive to change later.

How much design a task deserves

The guide is clear that most changes need none of this. It offers a rough ladder, which /poteto-mode already applies on its own:

SituationTool
A small, finished change you are unsure about/interrogate alone
A change that crosses function boundaries or moves ownership/architect, which brings in /arena when the design is large or contested
A standalone decision that independent attempts would improve (naming, formats, an algorithm)/arena directly
A coverage matrix, a set of parallel checks, or a race with declared arms/swarm
An open question that running something could answer (a layout, a timing, an approach)A prototype, not a debate
A contested design that is expensive to reverse/architect, then /interrogate before shipping
Work that spans several pull requestsA plan, written after the design settles

pstack has no dedicated planning skill. The Prototype and Multi-phase plan playbooks cover the last rows of this table: prototypes answer open questions by running code, and the plan is written only once the design has settled. Both are described in the playbook chapters.