/prototype

name: prototype
description: 'Use when a design question is cheaper to answer by clicking a throwaway artifact than by debating it: whether a state model or business rule behaves right, or which of several structurally different UI layouts works. Builds one scratch-only artifact (a self-contained shareable state demo, or switchable UI variants), observes it in a browser and reports evidence with a verdict or "inconclusive". Production routes, data and code stay untouched. Triggers on: "prototype this", "throwaway prototype", "clickable state demo", "does this state model feel right", "try a few UI variants", "compare layouts before committing". NOT for working a decision-map ticket, use decision-map. NOT for finished HTML deliverables such as dashboards or infographics, use static-web-artifacts-builder. NOT for UX audits or redesigns, use ux-expert.'
metadata:
  version: 1.0.2
  category: development
  tags: [prototyping, throwaway, state-model, ui-variants, design-questions]
  difficulty: intermediate
  phase: define
  complements:
    - decision-map
    - ux-expert

Prototype

A prototype is **throwaway code that answers one question**. The question decides the shape, the artifact lives in scratch space, and the answer comes from observing the artifact, not from reading its source. The verdict feeds separate implementation work; the prototype itself never becomes production code.

When to Use

| Situation | Package | |---|---| | "Does this state model / rule / transition logic hold up?" | `prototype` (logic branch) | | "What should this screen look like? Show me a few structurally different options" | `prototype` (UI branch) | | Working a `decision-map:prototype` ticket (claim, ticket evidence, frontier) | `decision-map`, which builds the artifact with this package | | A finished, polished HTML deliverable: dashboard, infographic, interactive diagram | `static-web-artifacts-builder` | | Audit or redesign an existing page against UX criteria | `ux-expert` |

Prerequisites and Authority

These boundaries hold in every branch:

• **Scratch only.** The artifact lives in a scratch location discovered from the repository (step 3), never in production paths or tracked implementation files.
• **No production-route edits.** To show a variant in its real surroundings, build a scratch copy or read-only reproduction of the host page and record the realism you gave up. Never modify a live route, layout or shared component to host the experiment.
• **Synthetic, in-memory data.** Representative, non-sensitive data held in memory. No production database, credentials, persistence, live mutations or dependency installation. If the question is about persistence itself, use explicitly disposable scratch storage, say so, and never connect production storage; if the question cannot be answered under these rules, stop and report the missing prerequisite.
• **No branch or commit by default.** Commit the prototype only if the user explicitly asks, and then only to a new throwaway branch (see Output).
• **Never lift prototype logic into production.** No extraction, winner promotion or automatic cutover. The verdict is input to separately authorized implementation work.
• **Browser before verdict.** An empirical verdict requires observing the actual artifact in a browser (any authorized browser automation or a browser the user drives and reports back from). Anything not exercised is labelled **not observed**.
• **Skip the polish.** Only the structure and error handling needed to run the experiment. No new framework setup, reusable architecture or test suite for the prototype; a UI scratch copy may use the project's existing framework when `references/ui.md` reuses its runner.

Workflow

1. Bound the question

Read the request and the relevant surrounding code. Write down, before building anything:

• the exact question, in one sentence;
• the competing answers;
• the scenario or comparison that would distinguish them;
• the assumptions you are making.

These go visibly at the top of the artifact as well. Keep a mixed question bounded to its deciding uncertainty; list other questions it raises as follow-ups instead of prototyping them too.

**Check that the answers actually diverge.** Name at least one scenario where the competing answers predict different visible outcomes. If none exists (the positions are compatible, or one is too underspecified to predict an outcome), there is nothing for a prototype to distinguish: ask the clarifying question that would make them diverge ("When a hold arrives after a granted renewal, is that renewal revoked?") and build only once a diverging scenario exists. If the user is unavailable, stop with verdict `inconclusive` and that question; do not invent the missing rule.

**Complete when** the question, competing answers, at least one diverging scenario and the assumptions are written down.

2. Pick exactly one branch

| Deciding uncertainty | Branch | Reference | |---|---|---| | Business logic, legal transitions, representable data shapes | **Logic**: one self-contained shareable HTML file | `references/logic.md` | | Layout, information hierarchy, primary interaction | **UI**: 3 structurally different variants (2–5) on one comparison surface | `references/ui.md` |

If the question is too vague to choose, ask one discriminator: **"Are we testing what the state model permits, or how the interface presents it?"** If the user is unavailable, choose only when the surrounding code clearly supports it (a backend module suggests logic; a page or component suggests UI) and state that assumption at the top of the artifact. Otherwise stop with verdict `inconclusive` and the exact clarification needed. Getting the branch wrong wastes the whole prototype.

3. Establish the scratch boundary

Discover where scratch work belongs from the repository's own configuration. Search the repository root (`git rev-parse --show-toplevel`, or the working directory outside g