---
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 one question**.
The question decides the branch.

## 1. Pick a branch

Identify the question from the user's prompt and surrounding code.
Ask when it remains genuinely ambiguous and the user is reachable.

- **Does this logic or state model feel right?**
  Follow [`LOGIC.md`](LOGIC.md) to build a tiny interactive terminal app that pushes the model through hard-to-reason-about cases.
- **What should this look like?**
  Follow [`UI.md`](UI.md) to build several radically different UI variants on one route with a URL-controlled switcher.

When the user is unavailable, default to Logic for a backend module and UI for a page or component, then state the assumption in the prototype.

Done when exactly one branch and one design question govern the prototype.

## Common rules

- **Throwaway from day one.**
  Locate the code close to where it would be used, but name it so nobody mistakes it for production.
  Follow the project's routing and source-layout conventions rather than inventing a new top-level structure.
- **One command to run.**
  Use the project's existing task runner so the user does not need to remember a path or setup sequence.
- **No persistence by default.**
  Keep state in memory unless persistence is the question being tested.
  Use an unmistakably disposable database or local file when that question requires one.
- **Skip polish.**
  Add no tests, production-grade error handling, speculative abstractions, or unrelated cleanup.
- **Surface state.**
  Show the full relevant state after every Logic action or UI variant switch.

## 2. Build and reach a verdict

Follow the selected branch through its handover step and iterate on the prototype in response to the user's feedback.
Do not treat a runnable prototype as the result.
The result is the verdict that answers the design question.

Done when the user has reached an explicit verdict or stated that the prototype did not resolve the question.

## 3. Capture the primary source

Commit the complete prototype to a throwaway branch outside main.
The branch is the primary source.

Resolve the artifact destination before naming the file.
When the caller provides a destination directory, use it exactly.
Otherwise, default to `$(xdg-user-dir DOCUMENTS)/ai-artifacts/projects/<project>` when the AI artifacts vault is available, where `<project>` is the lowercase basename of the current working directory.
If that vault is unavailable, fall back to `./docs` in the current project.
Create the destination directory only when needed.

Before choosing a filename, read the destination's `AGENTS.md`.
Use the naming convention declared there, or infer it from nearby artifacts when the file delegates naming to local context.
Do not assume a counter, numeric prefix, slug shape, or artifact-type suffix unless the destination convention requires it.
If no convention can be determined, choose the least surprising lowercase descriptive Markdown filename and state that the destination did not define a naming convention.

When the caller provides an allocated filename and `parent`, use them exactly and do not advance any counter.
Create only the Prototype artifact and leave the parent artifact unchanged.
Otherwise, allocate any identifier required by the destination convention and include `parent` only when an earlier artifact directly caused the prototype.

The Prototype artifact links the throwaway branch and preserves the question, run instructions, verdict, and branch-appropriate evidence:

- UI evidence uses screenshots.
- Logic evidence uses useful code snippets and, where needed, a short interaction transcript.

Done when the complete prototype is committed outside main and exactly one Prototype artifact preserves the result according to the destination convention.

## 4. Fold in the decision when permitted

A planning-only caller such as Wayfinder stops after the verdict and leaves production code unchanged.
Otherwise, fold the validated decision into production only when the caller permits implementation.
Follow the selected branch's **Production mapping** and keep all other throwaway code out of main.

Done when production is unchanged for a planning-only run, or contains only the permitted validated decision for an implementation run.