Prototype

A prototype is disposable code that answers a question faster than debate. Keep it close to the real area, make it easy to run, and optimize for learning rather than polish.

When to Use

• The user says "prototype this", "try a few designs", or "let me play with it"
• A state model or workflow is hard to reason about on paper
• You need several UI directions before picking one
• The fastest way to answer the question is to build a small runnable artifact

When NOT to Use

Instead of prototype	Use
You are building production-ready functionality	spec-driven-development
The main problem is root-cause analysis of broken code	diagnose
You already know the design and need safe cleanup	refactor-clean

Prerequisites

• A concrete question the prototype should answer
• A place near the target code where throwaway work can live temporarily
• One obvious command the user can run locally

Workflow

1. Choose the branch

Decide which question you are answering:

• Logic / state question — build a tiny runnable terminal or script-based prototype that pushes the state machine through the tricky cases
• UI question — build several clearly different visual variants that can be switched from one route, page, or entry point

If the question is ambiguous and the user is unavailable, match the surrounding code and state the assumption clearly at the top.

2. Mark it as throwaway from day one

Put the prototype near the feature it informs, but name it so nobody confuses it with production code. Follow the project's existing routing or directory conventions instead of inventing a brand-new top-level structure.

3. Make it runnable with one command

Use the project's existing runtime:

• npm run prototype:checkout
• python src\feature\prototype.py
• go run .\cmd\prototype

The user should not need a multi-step setup just to learn from the prototype.

4. Strip everything non-essential

Default rules:

• no persistence unless persistence itself is the question
• no tests unless the prototype is proving a test technique
• no extra abstractions
• only enough error handling to keep it runnable

5. Surface the state

After each action or branch change, print or render the relevant state so the user can see what changed and why.

6. Capture the answer, then delete or absorb

The lasting artifact is the decision, not the prototype. When the question is answered:

1. capture the takeaway in an issue, ADR, commit note, or nearby NOTES.md
2. either delete the prototype or fold the validated idea into real code

Examples

Logic prototype

Create a tiny checkout state-machine runner that lets the user toggle events like apply-coupon, expire-session, and submit-order, then prints the full state after each step.

UI prototype

Build three layout variants for the same page and expose a simple variant switcher so the user can compare them quickly without branching the whole app.

Common Rationalizations

Rationalization	Reality
"Let's make the prototype production-ready just in case"	That turns learning code into premature product code.
"We should hide the ugly internal state"	The whole point is to make the decision surface obvious.
"We'll remember what we learned later"	If the answer is not captured, the same question returns next session.

Red Flags

• The prototype grows tests, persistence, and abstractions unrelated to the question
• Nobody can tell how to run it in one command
• The artifact stays in the repo after the decision is made, with no cleanup plan
• The prototype answers multiple unrelated questions at once

Verification

• The prototype names the question it is answering
• One command runs it locally
• The relevant state or variant is visible after each interaction
• The resulting decision is captured somewhere durable before the prototype is kept or removed

Tips

• Prototype the smallest slice that can disprove a bad design quickly
• Put a short "throwaway prototype" note in the file header or surrounding docs
• Follow with refactor-clean if a successful prototype is later absorbed into production code