---
name: prototype
description: Use when a design question needs a runnable answer rather than a discussion, meaning whether a state model or flow holds up, or what a screen should look like. Triggers on "mock this up", "show me some options", "does this feel right".
---

# Prototype

A prototype is **throwaway code that answers one question**. The question decides the shape.

Throwaway is a constraint on how the code is written, not a promise to destroy it. The answer folds
into the real code; the prototype itself is kept as a primary source on a branch out of main.

## Pick the branch

Identify the question from the prompt, the surrounding code, or by asking:

| The question is | Branch | Artifact |
|---|---|---|
| "Does this logic or state model feel right?" | [LOGIC.md](LOGIC.md) | One self-contained HTML file anyone can drive by clicking |
| "What should this look like?" | [UI.md](UI.md) | Several structurally different variations to flip between |

The two produce very different artifacts, so getting this wrong wastes the whole prototype. Where it
is genuinely ambiguous and nobody is reachable, default by the surrounding code (a backend module
means logic, a page or component means UI) and state the assumption at the top of the prototype.

## The gate

<HARD-GATE>
Build the prototype, hand over the URL or file, and **stop**. Do not edit the real component, fold in
a winner, or start implementing until a decision comes back.
</HARD-GATE>

This is the point of the exercise. A prototype that flows straight into the implementation was just
an implementation with extra steps.

## Rules for both branches

1. **Throwaway from day one, and obviously so.** Put the code near what it prototypes, so the context
   is clear, but name it so a casual reader sees it is not production. Follow the project's existing
   routing and file conventions; invent no new top-level structure.
2. **Trivial to run.** A UI prototype is one URL. A logic demo is one file that opens on a
   double-click. No thinking required to start it.
3. **Do not start a dev server yourself.** Assume one may already be running. Where the prototype
   needs a server that is not up, or needs a restart, ask rather than starting it.
4. **No persistence by default.** State lives in memory. Persistence is usually the thing being
   *checked*, not something to depend on. Where the question genuinely involves the database, point
   at a scratch one named so nobody mistakes it.
5. **Skip the polish.** No tests, no error handling beyond what makes it run, no abstractions. A
   prototype that needs tests has stopped being a prototype.
6. **Surface the state.** After every action, or on every variant switch, render the full relevant
   state so the change is visible.
7. **Answer one question.** No "what if we also wanted X later".

## Capture it when the answer arrives

Once a variant or model has won:

1. **Capture the answer**: which option, and why. That sentence is the durable output, not the code.
2. **Fold the validated decision into the real code**, rewritten properly. Prototype code was written
   under prototype constraints and does not get promoted as-is.
3. **Push the prototype to a `prototype/<name>` branch, out of main**, and leave a pointer to that
   branch wherever the work is tracked. Variants and switchers left in main rot fast and confuse the
   next reader.

## Where this sits

A prototype is the detour when a question cannot be settled on paper. Where the wider design is still
open, call the Skill tool with "grilling" first and come back here for the one question that needs a
runnable answer.

**Not for a spike's mock deliverable.** Where a Jira ticket asks for mocks, the `ticket` skill owns
that: a rough working version in real code on the ticket branch, plus one or two polished visual
mocks, both shipped with the ticket rather than thrown away. Reach for this skill during a spike only
while the open question is genuinely which direction to build.
