Prototype

Prototype

The Core Idea

Prototypes are the thinking stage, not the shipping stage. Before you commit to a design—before you write the real code— you ask the hard question by building and running something small.

The single clearest question shapes everything: what you build, how long you spend, where you put your energy. Two very different questions need very different artifacts. Mixing them guarantees confusion and wasted effort.

Step 1 — Identify Your Question

What are you actually trying to learn?

Ambiguous? Default to the question type that matches your surrounding code:

• Backend module → logic (state/data question) → follow LOGIC.md
• Page or component → UI (interaction question) → follow UI.md
• State your assumption at the top of the prototype.

Step 2 — Locate and Name the Prototype

Place the prototype next to the code it is prototyping — same directory as the module or component it explores. Context should be obvious to you (or future-you) opening the folder six months from now.

Name it so a casual reader knows it's NOT production code:

✅ Good names:
  src/checkout/prototype-payment-flow/
  src/components/UserCard/prototype-redesign/
  app/dashboard/prototype-v2/

❌ Bad names:
  src/checkout/payment-flow/  ← looks production
  ProtoPayment.jsx            ← too cryptic

Create a README.md inside

Every prototype directory gets a README.md with exactly three sections:

# Prototype: [Name]

## The Question
[One sentence. What are you trying to learn?]

Example: "Can we validate email on-blur without blocking UX?"

## How to Run
[One command. Whatever you already use.]

Example: `npm run proto:payment` or `python prototype.py`

## Answer
[Blank until you run it. Fill this in before deletion.]

[Your findings go here after you're done prototyping]

As a solo developer, this README is the only thing standing between you and "why did I decide that?" three months from now. Nobody else will remember for you.

Step 3 — Build Throwaway, Not Production

Rules

1. No tests — A prototype that needs tests isn't a prototype anymore; it's becoming production code. Stop and refactor.

2. No real database — Use in-memory state, mock data, or a scratch file clearly labeled "PROTOTYPE—wipe me". Exception: if the prototype's question is specifically about persistence (caching behavior, replication), then hit a real scratch DB.

3. No generalization — "What if I wanted to support X later?" = wasted effort. This prototype answers one question. When done, you delete it or fold the validated logic into real code.

4. No error handling beyond runnable — Skip try/catch, skip logging infrastructure, skip graceful degradation. If it crashes, that's fine—you'll see it immediately.

5. Surface the state — After every action (in logic) or every variant switch (in UI), print or render the full relevant state. You must see what changed.

6. Delete or absorb — When the prototype answers its question, one of two things happens:

   • Delete it entirely, OR
   • Extract the validated logic and fold it into production code

   Don't leave prototypes rotting in the repo for months.

Step 4 — Capture the Answer and Clean Up

Before You Delete

The prototype will disappear, but the insight must stay. You have one sitting to capture it — once the terminal window closes, the "aha" moment is gone.

1. Write the answer into a durable place:

   • The README.md → Answer section (see Step 2)
   • An ADR: docs/adr/NNNN-why-i-chose-X.md
   • A commit message on the branch where you fold in the validated logic
   • A DESIGN.md in the component folder

2. One sentence minimum: "This turned out to matter more than I expected because..."

3. Delete the prototype folder (or the branch, or the file—whatever you created)

For Solo Developers

Working alone changes what you need from a prototype process. There's no teammate to catch you if you skip a step — so the discipline has to be self-imposed.

The Solo Checklist

Before you delete a prototype, ask yourself out loud (yes, actually):

• Did this answer my stated question, or did I get distracted and build something else?
• Would I remember this decision in 3 months without the note I'm about to write?
• Is there a validated piece of logic here worth keeping, or is it 100% throwaway?

Fighting "Just Ship the Prototype" Temptation

Solo developers are the most likely to skip the cleanup step, because there's no code review gate forcing it. The fix: name it so ugly you're embarrassed to ship it. prototype-DELETE-ME-checkout/ is harder to accidentally merge than checkout-v2/.

Future-You Is a Different Person

Write the README as if explaining it to a stranger — because in 3 months, you are one. Don't write "obviously we chose X" — write "I chose X because Y, and rejected Z because W."

Common Failures (Learn from these)

Trap 1: The "Swiss Army Knife" Prototype

You try to answer 3 questions at once: state + UI + performance.

• Result: A franken-artifact that confuses even you, a week later.
• Fix: One question per prototype. When done, delete it and start fresh.

Trap 2: Prototype Rot

It works so well that you just... keep building on it instead of writing it "properly." Now you're maintaining throwaway code for years.

• Fix: Name it obviously (prototype-*). Delete it the day after you ship the real thing.
• Better: Build it on a branch, not main — delete the branch when you're done.

Trap 3: The Forgotten Answer

You built a brilliant prototype, learned something, deleted it. Three months later: "Why did I choose that design?" You don't remember, and there's no teammate to ask either.

• Fix: Before deletion, write the answer into DESIGN.md or an ADR (10 minutes).
• Even better: Link that note from the component's README so future-you finds it.

Quick Reference

References

This skill is inspired by mattpocock/skills/prototype by Matt Pocock, which introduced the core insight that a single clear question shapes the entire prototype, and the two-branch routing between logic (terminal/state) and UI (multi-variant) prototypes.

Matt's version is built for engineers on teams shipping production code fast.

This version adapts that framework for solo and independent developers, who don't have a teammate to catch skipped steps or forgotten decisions. Key differences:

What's kept from Matt's original:

• The core insight: "the question decides the shape"
• The two-branch routing (logic vs. UI)
• The discipline: throwaway from day 1, no persistence, no tests

What's added here (original content):

• A table-based decision framework with the "why" spelled out
• Structured README template (question + how-to + answer)
• A "For Solo Developers" section — self-imposed checklists instead of code review gates
• "Common Failures" — three anti-patterns specific to working without a team
• Emphasis on documentation for future-you, since there's no one else to ask later

Both versions share the same philosophy: write down your question first. That one sentence decides everything.