git:20260815.14d67ac to git:20260831.64fb3ee

7 added, 7 removed. Audit B to B.

---

name: prototype

description: Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

---

# Prototype

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

## Pick a branch

- Identify which question is being answered — from the user's prompt, the surrounding code, or by asking if the user is around:

+ Identify which question is being answered: from the user's prompt, the surrounding code, or by asking if the user is around:

- - **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.

+ - **"Does this logic / state model feel right?"** → [LOGIC.md](LOGIC.md). Build a single shareable HTML file (free-play buttons plus tabbed guided walkthroughs) that pushes the state machine through cases that are hard to reason about on paper, and that a non-developer can drive.

- **"What should this look like?"** → [UI.md](UI.md). Generate several radically different UI variations on a single route, switchable via a URL search param and a floating bottom bar.

- The two branches produce very different artifacts — getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.

+ The two branches produce very different artifacts: getting this wrong wastes the whole prototype. If the question is genuinely ambiguous and the user isn't reachable, default to whichever branch better matches the surrounding code (a backend module → logic; a page or component → UI) and state the assumption at the top of the prototype.

## Rules that apply to both

- 1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious — but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.

- 2. **One command to run.** Whatever the project's existing task runner supports — `php artisan <name>`, `composer <script>`, `pnpm <name>`, `python <path>`, etc. The user must be able to start it without thinking.

- 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE — wipe me" name.

+ 1. **Throwaway from day one, and clearly marked as such.** Locate the prototype code close to where it will actually be used (next to the module or page it's prototyping for) so context is obvious, but name it so a casual reader can see it's a prototype, not production. For throwaway UI routes, obey whatever routing convention the project already uses; don't invent a new top-level structure.

+ 2. **Trivial to run.** A UI prototype starts from one command in the project's existing task runner: `php artisan <name>`, `composer <script>`, `pnpm <name>`, `python <path>`. A logic demo is a single HTML file the user double-clicks. Either way, no thinking required to start it.

+ 3. **No persistence by default.** State lives in memory. Persistence is the thing the prototype is _checking_, not something it should depend on. If the question explicitly involves a database, hit a scratch DB or a local file with a clear "PROTOTYPE, wipe me" name.

4. **Skip the polish.** No tests, no error handling beyond what makes the prototype _runnable_, no abstractions. The point is to learn something fast.

5. **Surface the state.** After every action (logic) or on every variant switch (UI), print or render the full relevant state so the user can see what changed.

- 6. **Capture it when done.** Capture the prototype itself as a **primary source**: keep it as a clearly-named throwaway file (never a git branch), and leave a context pointer to it on the ticket via the tracker's Assets operation. Capture the answer too — the verdict and the question it settled — on the ticket. Fold only the validated *decision* onward: into the ticket's Resolution or the spec while charting, into real code once building. The codebase keeps the validated decision, never the prototype.

+ 6. **Capture it when done.** Capture the prototype itself as a **primary source**: keep it as a clearly-named throwaway file (never a git branch), and leave a context pointer to it on the ticket via the tracker's Assets operation. Capture the answer too (the verdict and the question it settled) on the ticket. Fold only the validated *decision* onward: into the ticket's Resolution or the spec while charting, into real code once building. The codebase keeps the validated decision, never the prototype.