prototype

name

prototype

description

Build a throwaway prototype to flesh out a design before committing to it. Routes between two branches — a runnable terminal app for state/business-logic questions, or several radically different UI variations toggleable from one route. Use when the user wants to prototype, sanity-check a data model or state machine, mock up a UI, explore design options, or says "prototype this", "let me play with it", "try a few designs".

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:

• "Does this logic / state model feel right?" → the Logic prototype below. Build a tiny interactive terminal app that pushes the state machine through cases that are hard to reason about on paper.
• "What should this look like?" → the UI prototype below. 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.

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 — pnpm <name>, python <path>, bun <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.
4. Skip the polish. No tests, no error handling beyond what makes the prototype runnable, no abstractions. The point is to learn something fast and then delete it.
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. Delete or absorb when done. When the prototype has answered its question, either delete it or fold the validated decision into the real code — don't leave it rotting in the repo.

When done

The answer is the only thing worth keeping from a prototype. Capture it somewhere durable along with the question it was answering:

• An ADR under .context/adr/ when the answer is an architectural decision.
• A PRD via to-prd (.context/prd/), or directly as iudex tickets via to-issues, when the prototype validated something you're now ready to build.
• A NOTES.md next to the prototype as a placeholder if neither fits yet.

If the user is around, that capture is a quick conversation; if not, leave the placeholder so they (or you, on the next pass) can fill in the verdict before deleting the prototype.

---

Logic prototype

A tiny interactive terminal app that lets the user drive a state model by hand. Use this when the question is about business logic, state transitions, or data shape — the kind of thing that looks reasonable on paper but only feels wrong once you push it through real cases.

When this is the right shape:

• "I'm not sure if this state machine handles the edge case where X then Y."
• "Does this data model actually let me represent the case where..."
• "I want to feel out what the API should look like before writing it."
• Anything where the user wants to press buttons and watch state change.

Process

1. State the question. Before writing code, write down what state model and what question you're prototyping. One paragraph, in the prototype's README or a top-of-file comment. A logic prototype that answers the wrong question is pure waste — make the question explicit so it can be checked later, whether the user is watching now or returning AFK.

2. Pick the language. Use whatever the host project uses. If the project has no obvious runtime (e.g. a docs repo), ask. Match existing tooling conventions — don't add a new package manager or runtime just for the prototype.

3. Isolate the logic in a portable module. Put the actual logic — the bit answering the question — behind a small, pure interface that could be lifted out and dropped into the real codebase later. The TUI around it is throwaway; the logic module shouldn't be. The right shape depends on the question:

   • A pure reducer — (state, action) => state. Good when actions are discrete events and state is a single value.
   • A state machine — explicit states and transitions. Good when "which actions are even legal right now" is part of the question.
   • A small set of pure functions over a plain data type. Good when there's no implicit current state — just transformations.
   • A class or module with a clear method surface when the logic genuinely owns ongoing internal state.

   Pick whichever fits the question, not whichever is easiest to wire to a TUI. Keep it pure: no I/O, no terminal code, no console.log for control flow. The TUI imports it and calls into it; nothing flows the other direction. This is what makes the prototype useful past its own lifetime.

4. Build the smallest TUI that exposes the state. A lightweight TUI — on every tick, clear the screen (console.clear() / print("\033[2J\033[H") / equivalent) and re-render the whole frame. The user should always see one stable view, not ever-growing scrollback. Each frame has two parts, in order:

   1. Current state, pretty-printed and diff-friendly (one field per line, or formatted JSON). Use bold for field names/headers (\x1b[1m) and dim for less important context like timestamps/IDs (\x1b[2m), reset with \x1b[0m. No styling library needed unless one's already in the project.
   2. Keyboard shortcuts at the bottom: [a] add user [d] delete user [t] tick clock [q] quit.

   Behaviour: initialise state as a single in-memory object and render the first frame on start; read one keystroke (or line) at a time and dispatch to a handler that mutates state; re-render the full frame after every action (replace, don't append); loop until quit. The whole frame should fit on one screen.

5. Make it runnable in one command. Add a script to the project's existing task runner (package.json scripts, Makefile, justfile, pyproject.toml). The user runs pnpm run <name> or equivalent — never a path. If there's no task runner, put the command at the top of the prototype's README.

6. Hand it over. Give the user the run command. The interesting moments are when they say "wait, that shouldn't be possible" — those are bugs in the idea, the whole point. Add new actions if they ask.

7. Capture the answer. When done, the answer is the only thing worth keeping. If the user is around, ask what it taught them; if not, leave a NOTES.md next to the prototype to fill in before deletion.

Anti-patterns:

• Don't add tests. A prototype that needs tests is no longer a prototype.
• Don't wire it to the real database. Use an in-memory store unless the question is specifically about persistence.
• Don't generalise. No "what if we wanted to support X later." The prototype answers one question.
• Don't blur the logic and the TUI together. If the reducer / state machine references console.log, prompts, or escape codes, it's no longer portable.
• Don't ship the TUI shell into production. The shell is for being driven by hand; the logic module behind it is the bit worth keeping.

---

UI prototype

Generate several radically different UI variations on a single route, switchable from a floating bottom bar. The user flips between variants in the browser, picks one (or steals bits from each), then throws the rest away.

When this is the right shape:

• "What should this page look like?"
• "I want to see a few options for this dashboard before committing."
• "Try a different layout for the settings screen."
• Any time the user would otherwise spend a day picking between three vague mockups in their head.

Two sub-shapes — strongly prefer sub-shape A

A UI prototype is much easier to judge when it's butting up against the rest of the app — real header, real sidebar, real data, real density. A throwaway route on its own is a vacuum: every variant looks fine in isolation. Default to sub-shape A whenever there's a plausible existing page to host the variants.

• Sub-shape A — adjustment to an existing page (preferred). The route already exists. Variants render on the same route, gated by a ?variant= URL search param. Existing data fetching, params, and auth all stay — only the rendering swaps. If the prototype is for something that doesn't yet have a page but would naturally live inside one (a new dashboard section, a new settings card, a new step in a flow), that's still sub-shape A — mount the variants inside the host page.
• Sub-shape B — a new page (last resort). Only when the thing genuinely has no existing page to live inside (an entirely new top-level surface). Create a throwaway route following the project's existing routing convention — don't invent new top-level structure. Name it so it's obviously a prototype (include prototype in the path/filename). Same ?variant= pattern. Before committing to B, sanity-check there's really no existing page to embed in.

In both sub-shapes the floating bottom bar is identical.

Process

1. State the question and pick N. Default to 3 variants. More than 5 stops being radically different and starts being noise — cap there. Write the plan in one line, in the prototype's location or a top-of-file comment: "Three variants of the settings page, switchable via ?variant=, on the existing /settings route."

2. Generate radically different variants. Hold each to: the page's purpose and the data it has access to; the project's component library / styling system (Tailwind, shadcn, MUI, plain CSS, whatever); a clear exported component name (VariantA, VariantB, VariantC). Variants must be structurally different — different layout, information hierarchy, primary affordance, not just colours. Three slightly-tweaked card grids isn't a UI prototype, it's wallpaper. If two drafts come out too similar, redo one with explicit "do not use a card grid" guidance.

3. Wire them together. A single switcher component on the route:

   // pseudo-code — adapt to the project's framework
   const variant = searchParams.get('variant') ?? 'A';
   return (
     <>
       {variant === 'A' && <VariantA {...data} />}
       {variant === 'B' && <VariantB {...data} />}
       {variant === 'C' && <VariantC {...data} />}
       <PrototypeSwitcher variants={['A','B','C']} current={variant} />
     </>
   );
   

   Sub-shape A: keep all existing data fetching above the switcher; only the rendered subtree changes per variant. Sub-shape B: the throwaway route mounts the same switcher.

4. Build the floating switcher. A small fixed-position bar at bottom-centre with three pieces: left arrow (previous variant, wraps), variant label (current key and, if exported, its name — e.g. B — Sidebar layout), right arrow (forward, wraps). Behaviour:

   • Clicking an arrow updates the URL search param (use the framework's router — router.replace on Next, navigate on React Router) so the variant is shareable and reload-stable.
   • Keyboard: ← and → also cycle. Don't intercept arrow keys when an <input>, <textarea>, or [contenteditable] is focused.
   • Visually distinct from the page (high-contrast pill, subtle shadow) so it's obviously not part of the design being evaluated.
   • Hidden in production builds — gate on process.env.NODE_ENV !== 'production' or equivalent, so a stray prototype merge can't ship the bar.

   Put the switcher in a single shared component so both sub-shapes reuse it.

5. Hand it over. Surface the URL (and the ?variant= keys). The interesting feedback is usually "I want the header from B with the sidebar from C" — that's the actual design they want.

6. Capture the answer and clean up. Once a variant wins, write down which and why (commit message, an ADR under .context/adr/, a PRD via to-prd, or a NOTES.md). Then: Sub-shape A — delete the losing variants and the switcher; fold the winner into the existing page. Sub-shape B — promote the winner to a real route, delete the throwaway route and the switcher. Don't leave variant components or the switcher lying around.

Anti-patterns:

• Variants that differ only in colour or copy. That's a tweak, not a prototype. Real variants disagree about structure.
• Sharing too much code between variants. A shared <Header> is fine; a shared <Layout> defeats the point.
• Wiring variants to real mutations. Read-only prototypes are fine. If a variant needs to mutate, point it at a stub.
• Promoting the prototype directly to production. It was written under prototype constraints (no tests, minimal error handling). Rewrite it properly when you fold it in.