/prototype

name: prototype
description: 'Use when asked to prototype one design question through a cheap logic or UI experiment, including button-driven state-model checks. Not for polished artifacts: use polished-web-prototype.'

Prototype

Contract

| Field | Bound contract | |---|---| | Trigger | Explicit model invocation: one design question needs a cheap logic or UI experiment, including a state-model, logic, or data-shape question a human checks by pressing buttons and watching state change, even when the driver is a non-developer. | | Authority | Reversible local: writes throwaway prototype artifacts and their verdict on a throwaway branch off main; may fold the validated decision into the named real-code target as a working-tree edit the user commits through their normal flow; rollback is abandoning the throwaway branch or restoring its commits. Never push, delete existing work, or change production rendering. No remote mutation. | | Side effect | Write one throwaway prototype artifact and its verdict off the main branch; that branch is the evidence, not a delivery target. | | Done | The question is answered in one line and the decision is folded into the real work. |

Inputs

• Question (required): the design question being answered, drawn from the user's prompt or surrounding code. If the question is genuinely ambiguous and the user is reachable, ask before routing.
• Context (required): the surrounding code or page that frames the question. Determines whether to route to LOGIC or UI.
• LOGIC mode also takes: the relevant state, actions, domain terms, and legal-transition rules; a path for the throwaway HTML file; representative scenarios or enough domain rules to derive a happy path, a tricky edge case, and an illegal-action attempt; the main branch the throwaway branch is based on; and a real-code target, required only after the human validates the module.

Procedure

Route

Route before writing because LOGIC and UI variants require different artifact structures.

1. Classify the question:

• Logic: state machine, edge case, data shape, reducer, API contract, or "does this feel right" → use the LOGIC procedure below.
• UI: what something should look like, layout, information hierarchy, or "what should this look like" → use the UI procedure below.

2. If ambiguous and the user is not reachable, default: backend module → LOGIC; page or component → UI. State the assumption at the top of the artifact. Done when: the question is classified as LOGIC or UI, or the ambiguity default is stated and recorded on the artifact.

LOGIC procedure

*When the question is about business logic, state transitions, or data shape.*

1. Bound the change and state the question. Inspect the named paths and current version-control state; bound the change to the throwaway HTML path and, only after validation, the supplied real-code target. Stop if either target would overwrite unrelated work, the main-branch basis is unavailable, or a required domain rule cannot be established without guessing. Write one paragraph at the top of the demo stating the exact question and the state model being tested. This checkpoint prevents the prototype from answering the wrong question. Done when: the change is bounded, no target overwrites unrelated work or guesses a domain rule, and the artifact's top paragraph names the exact question and the state model. 2. Isolate the logic. Put the answerable logic in a single `<script>` block as a small pure module. Pick the shape that fits the question:

• Pure reducer: `(state, action) => state`, for discrete events and a single state value.
• State machine: explicit states and transitions, when legality of actions depends on current state.
• Pure functions over a plain data type, when there is no implicit current state.
• Class or module with a clear method surface, when logic genuinely owns ongoing internal state.

Keep it pure: no DOM, no `document`, no button handlers reaching inside it; the page may call the module, but the module must not call back into the page. This module must be liftable into the real codebase after the question is answered. Done when: the logic sits in one pure module with no DOM or event-handler coupling, and the module's shape matches the question type from the list above. 3. Build the shareable HTML file. One file, plain HTML/CSS/JS, everything inline, opens by double-click. No framework, no bundler, no server. Mark the filename and the visible page as throwaway. Layout, top to bottom:

• Title and one-line explanation of the question.
• Current state panel: full relevant state rendered in domain language (not raw JSON), re-rendered after every click so the change is visible. Call out what just changed where it helps a non-developer follow.
• Free-play buttons: one button per action, always available. Each click dispatches its action and re-renders the state.
• Guided walkthroughs: tabs, each containing a plain-language description of the scenario and the ordered buttons to press. Clicking a step button performs that action and advances. Each walkthrough resets to a known initial state before running so reruns are deterministic. Cover all three scenario classes: the happy path, a tricky edge case, and an attempt at something that should be illegal.

Write every label in domain language, not code. Keep it clean: one accent colour, generous spacing, no animations, no gimmicks. Done when: the HTML file opens by double-click with no server, shows the state panel, free-play buttons, and at least one guided walkthrough per scenario class, and every label is domain language rather than code identifiers. 4. Exercise it, then hand it over. Before surfacing, open the standalone file, exercise free play and all three scenario classes, and confirm that every action visibly produces the modeled state transition, including rejection or handling of the illegal action. Repair only defects that prevent the demo from ans