Prototype
Paths below are relative to this skill's directory; resolve them to absolute
paths before running anything.
A prototype is throwaway code that answers a question, and the question
decides the shape. You are not building the thing: you are buying an answer as
cheaply as possible, then keeping only what you learned.
Configuration
This repository's agent configuration should have been provided to you (the
## Agent skills block pointing at docs/agents/). If it is missing, use the
defaults below and suggest the user run the setup-aclarify-skills skill.
- Scratch folder (
docs/agents/workspace.md). Default: .scratchpad/,
git-ignored. Single-file prototypes with no code home go here.
- Issue tracker (
docs/agents/issue-tracker.md). Default: the repository's
GitHub issues through gh, if it has a GitHub remote. The verdict is recorded
there.
- Glossary (
docs/agents/domain.md). Default: GLOSSARY.md at the
repository root. A logic demo speaks its terms, where one exists.
Pick a branch
Name the question first, from the user's prompt, the surrounding code, or by
asking if the user is around:
- "Does this logic / state model / data shape feel right?" → read
references/logic.md. Build a single shareable HTML file (free-play buttons
plus tabbed guided walkthroughs) that pushes the state machine through cases
that are hard to reason about on paper, and that a non-developer can drive.
- "What should this look like?" → read
references/ui.md. Generate several
radically different UI variations, switchable via a URL search param and a
floating bottom bar, as close to the real app as fidelity allows.
The two branches produce very different artifacts, so the wrong branch wastes the
whole prototype. When the question is genuinely ambiguous, ask the user which
branch, recommending the one the surrounding code suggests (a backend module →
logic; a page or component → UI). Ask using your structured-question tool if you
have one; otherwise list numbered options in plain text and stop until they reply.
If the user is unreachable (you are running unattended), default to the branch
the surrounding code suggests and write the assumption at the top of the
prototype so a reader can correct it.
Rules for both branches
- Throwaway from day one, and marked as such. Put the code close to what it's
prototyping, so context is obvious, but name it so nobody mistakes it for
production:
prototype in the path or filename. For throwaway UI routes,
follow the routing convention the project already uses; don't invent new
top-level structure.
- A single-file prototype with no code home goes in the scratch folder.
Load the
scratchpad skill (through your skill tool, /scratchpad, or by
reading its SKILL.md) to place it; if it is not installed, write it under the
scratch folder yourself and make sure that folder is git-ignored.
- An in-repository prototype (an app route, a component story) lives on a
branch named
proto/<slug> that is never merged into the default
branch. If the work needs to be seen, hand off a URL or a screenshot, not a
pull request. The branch is a dead end: if a ticket drove you here, what the
ticket ships is the fold-in rewrite, never this branch. The proto/ prefix
makes "never merged" checkable at a glance instead of a hope.
- Trivial to run. A UI prototype starts from one command in the project's
task runner (
npm run <name>, python <path>, bun <path>, and so on). A
logic demo is a single HTML file the user double-clicks. Either way, starting
it takes no thought.
- No persistence by default. State lives in memory. Persistence is usually
the thing the prototype is checking, not something to depend on. If the
question really is about stored data, point at a scratch database or local
file clearly named to be wiped ("PROTOTYPE, wipe me"), never real data.
- Skip the polish. No tests, no error handling beyond what makes it
runnable or drivable (the variant switcher is drivability, not polish), no
abstractions, no "what if we later want X". The point is to learn something
fast. A prototype is exempt from the project's done-bar (its test, lint,
localisation and coverage rules): write copy inline in plain domain language
rather than through the project's i18n layer, for instance. The floor stays: it
must still run (rule 2) and never touch real data (rule 3).
- Surface the state. After every action (logic) or on every variant switch
(UI), render the full relevant state plainly, so what changed is impossible to
miss.
- Capture it when done, as below.
Fold-in is a rewrite, not a promotion
Prototype code was built under relaxed rules, so the validated decision gets
rebuilt properly through the project's real path: its components and tokens, its
i18n, its tests, its full done-bar. The prototype is a faithful starting point
and a reference, never the production artifact. Do not carry the prototype's
exemptions into the real code.
Capture: fold in the answer, archive the code
- Fold the validated decision into real code, as a rewrite: the validated
reducer or machine becomes its module's starting point; the winning UI variant
is rebuilt with the project's real components.
- Archive the prototype as a primary source. Losing variants, the switcher
and the HTML shell go to the
proto/<slug> branch: durable in git and
reachable by others, never in the default branch. The scratch folder is fine
for a genuinely disposable single-file demo, but it is git-ignored, so it is
scratch, not an archive anyone else can find; commit a demo worth keeping to
the proto/<slug> branch.
- Record the verdict where it will outlive the code: the question it
settled, the answer, and a pointer to the
proto/<slug> branch. The verdict,
not the code, is the real deliverable. If an issue drove this, it goes there;
if you were invoked with no issue, open one in the configured tracker, or put
it in the commit message on the proto/ branch, rather than leaving the
learning in a session about to end. A decision that sets precedent or is hard
to reverse is a candidate for the decision-record skill, if it is installed;
propose it, and let the user say yes.
1---2name: prototype3description: >-4 Builds a throwaway prototype that answers one design question: a single-file HTML demo5 driving a state model, or radically different UI variants on one route, then folds only6 the validated decision into real code. Use whenever someone wants to try something out7 before committing to it: "prototype this", "mock it up", "spike it", "does this logic8 feel right", "will this state machine hold up", "try a few layouts", "show me options9 before we build", "a throwaway demo a non-developer can drive", even when they don't say10 "prototype". Do NOT use to build or polish the real thing for keeps, or to settle a11 choice by interview (use `grill-me`).12license: MIT13argument-hint: '[the design question to answer]'14metadata:15 source: https://skillmd.com/skills/spencermarx/prototype16 credits: "Adapted from Matt Pocock's prototype skill, https://github.com/mattpocock/skills (MIT)"17---1819# Prototype2021Paths below are relative to this skill's directory; resolve them to absolute22paths before running anything.2324A prototype is **throwaway code that answers a question**, and **the question25decides the shape**. You are not building the thing: you are buying an answer as26cheaply as possible, then keeping only what you learned.2728## Configuration2930This repository's agent configuration should have been provided to you (the31`## Agent skills` block pointing at `docs/agents/`). If it is missing, use the32defaults below and suggest the user run the `setup-aclarify-skills` skill.3334- **Scratch folder** (`docs/agents/workspace.md`). Default: `.scratchpad/`,35 git-ignored. Single-file prototypes with no code home go here.36- **Issue tracker** (`docs/agents/issue-tracker.md`). Default: the repository's37 GitHub issues through `gh`, if it has a GitHub remote. The verdict is recorded38 there.39- **Glossary** (`docs/agents/domain.md`). Default: `GLOSSARY.md` at the40 repository root. A logic demo speaks its terms, where one exists.4142## Pick a branch4344Name the question first, from the user's prompt, the surrounding code, or by45asking if the user is around:4647- **"Does this logic / state model / data shape feel right?"** → read48 `references/logic.md`. Build a single shareable HTML file (free-play buttons49 plus tabbed guided walkthroughs) that pushes the state machine through cases50 that are hard to reason about on paper, and that a non-developer can drive.51- **"What should this look like?"** → read `references/ui.md`. Generate several52 radically different UI variations, switchable via a URL search param and a53 floating bottom bar, as close to the real app as fidelity allows.5455The two branches produce very different artifacts, so the wrong branch wastes the56whole prototype. When the question is genuinely ambiguous, ask the user which57branch, recommending the one the surrounding code suggests (a backend module →58logic; a page or component → UI). Ask using your structured-question tool if you59have one; otherwise list numbered options in plain text and stop until they reply.60If the user is unreachable (you are running unattended), default to the branch61the surrounding code suggests and **write the assumption at the top of the62prototype** so a reader can correct it.6364## Rules for both branches65661. **Throwaway from day one, and marked as such.** Put the code close to what it's67 prototyping, so context is obvious, but name it so nobody mistakes it for68 production: `prototype` in the path or filename. For throwaway UI routes,69 follow the routing convention the project already uses; don't invent new70 top-level structure.71 - **A single-file prototype with no code home** goes in the scratch folder.72 Load the `scratchpad` skill (through your skill tool, `/scratchpad`, or by73 reading its SKILL.md) to place it; if it is not installed, write it under the74 scratch folder yourself and make sure that folder is git-ignored.75 - **An in-repository prototype** (an app route, a component story) lives on a76 branch named **`proto/<slug>`** that is **never merged** into the default77 branch. If the work needs to be seen, hand off a URL or a screenshot, not a78 pull request. The branch is a dead end: if a ticket drove you here, what the79 ticket ships is the fold-in rewrite, never this branch. The `proto/` prefix80 makes "never merged" checkable at a glance instead of a hope.812. **Trivial to run.** A UI prototype starts from one command in the project's82 task runner (`npm run <name>`, `python <path>`, `bun <path>`, and so on). A83 logic demo is a single HTML file the user double-clicks. Either way, starting84 it takes no thought.853. **No persistence by default.** State lives in memory. Persistence is usually86 the thing the prototype is _checking_, not something to depend on. If the87 question really is about stored data, point at a scratch database or local88 file clearly named to be wiped ("PROTOTYPE, wipe me"), never real data.894. **Skip the polish.** No tests, no error handling beyond what makes it90 _runnable or drivable_ (the variant switcher is drivability, not polish), no91 abstractions, no "what if we later want X". The point is to learn something92 fast. A prototype is exempt from the project's done-bar (its test, lint,93 localisation and coverage rules): write copy inline in plain domain language94 rather than through the project's i18n layer, for instance. The floor stays: it95 must still run (rule 2) and never touch real data (rule 3).965. **Surface the state.** After every action (logic) or on every variant switch97 (UI), render the full relevant state plainly, so what changed is impossible to98 miss.996. **Capture it when done**, as below.100101## Fold-in is a rewrite, not a promotion102103Prototype code was built under relaxed rules, so the validated decision gets104rebuilt properly through the project's real path: its components and tokens, its105i18n, its tests, its full done-bar. The prototype is a faithful starting point106and a reference, never the production artifact. Do not carry the prototype's107exemptions into the real code.108109## Capture: fold in the answer, archive the code1101111. **Fold the validated decision into real code**, as a rewrite: the validated112 reducer or machine becomes its module's starting point; the winning UI variant113 is rebuilt with the project's real components.1142. **Archive the prototype as a primary source.** Losing variants, the switcher115 and the HTML shell go to the `proto/<slug>` branch: durable in git and116 reachable by others, never in the default branch. The scratch folder is fine117 for a genuinely disposable single-file demo, but it is git-ignored, so it is118 scratch, not an archive anyone else can find; commit a demo worth keeping to119 the `proto/<slug>` branch.1203. **Record the verdict where it will outlive the code**: the question it121 settled, the answer, and a pointer to the `proto/<slug>` branch. The verdict,122 not the code, is the real deliverable. If an issue drove this, it goes there;123 if you were invoked with no issue, open one in the configured tracker, or put124 it in the commit message on the `proto/` branch, rather than leaving the125 learning in a session about to end. A decision that sets precedent or is hard126 to reverse is a candidate for the `decision-record` skill, if it is installed;127 propose it, and let the user say yes.