The best specs are written at the moment of most knowledge, which usually means after something real has answered the open question. This page is the technique half of Explore first, then capture: which routes answer which questions, how much fidelity to buy, and what happens to the code you built to find out.
Capture takes whatever carries the intent. None of these is a requirements document, and all of them are valid inputs:
| Input | Typical source |
|---|---|
| A conversation with the agent | One person thinking out loud |
| A multi-person conversation with the agent | Refinement session, mob discovery |
| A briefing package (markdown, half-formed) | Cross-functional kickoff, domain expert dump |
| A business-language requirements doc | Customer-facing commitment, BRD, account team |
| A working prototype | PM, designer, or engineer who built the thing to find out |
| A generated interface image | Design exploration against your style guide |
| An eval or benchmark result | The evidence decided it, capture records why |
| A spike you are about to throw away | Revert the code, keep the understanding |
The last four are the ones teams underuse most.
The strongest version of the loop, and the one worth teaching first:
flowchart LR Q["Open question<br/>(how should it look / behave?)"] --> P["Prototype<br/>1-3 variants, throwaway"] P --> R["React & iterate<br/>at high fidelity"] R --> C["Capture spec<br/>from the prototype"] C --> I["Interview<br/>closes the gaps"] I --> PL["Plan<br/>rules on the code"] PL --> W["Work"]
Build the thing badly, on purpose, to find out what it should be. Then capture a spec from the prototype and tell the agent to ignore the code quality - what you want out of it is the ideation and the requirements it proved, not its implementation.
Vibe-code a prototype, then let it write the spec.
"capture a spec from this prototype - ignore the code quality, I want the product intent and the requirements it demonstrates" ✓ The prototype answered the design question at a fidelity a discussion could not reach. Capture harvests the answer; the plan stage decides separately what happens to the code.
Scale it up when the question is genuinely open: generate three radically different takes, react to all three, converge on a fourth. The variants do the work an argument cannot - it is much easier to say “the search box from A, the layout from C” than to specify either in prose.
Three takes, hill-climb, then spec the winner.
"build three radically different prototypes of this, let me react to each, then capture the winner as a spec with the rejected options and why they lost" ✓ The losing variants are evidence, not waste - recording why they lost stops the same idea coming back in three months. Only the decision and its rationale land in the spec.
More compose recipes →Not every question needs running code. The decision rule is fidelity: how concrete does the artifact have to be before the question can actually be answered?
| Question | Fidelity needed |
|---|---|
| ”Should the modal have cancel and confirm?” | Discussion. Just decide. |
| ”What are the acceptance criteria for this rule?” | Discussion, then interview. |
| ”How should this look?” / “How should this behave?” | Prototype. No amount of prose settles it. |
| ”Does this state model feel right in the awkward cases?” | Prototype. A logic prototype, not a UI one. |
| ”Which of these three approaches actually performs?” | Prototype, or a task-per-candidate bake-off. |
Two things follow from taking fidelity seriously.
Prototyping is not a front-end activity. The reflex is to reach for a prototype only when there is a screen involved, and that reflex leaves the hardest questions unanswered. A logic prototype - a tiny interactive harness that pushes a state machine through the cases that are hard to reason about on paper - answers “does this model survive the real world?” better than any design document. Backend work is where the expensive misunderstandings live.
Fidelity costs tokens, and that is a real budget. A discussion is cheap and gives cheap answers. A prototype costs real tokens and gives an answer you can trust. Buy fidelity where being wrong is expensive; stay in discussion where it is not. The cost of producing code has collapsed, which is exactly why prototyping is now the cheap option it never used to be - but it is not free, and pretending otherwise is how token budgets get burned on questions a two-minute conversation would have closed.
The payoff is a shorter final leap. Going from a spec to production-ready code is a big jump. Going from a working prototype to production is a small one, because the hard questions were answered against something real.
/flow-next:chart is where this doctrine stops being prose and becomes a discovery loop. A chart’s decision types are the evidence-first routes - research, probe, eval, prototype, interview, task - and each decision is sized for one agent session. Chart adapts after every answer, preserves wrong turns via supersession, and hands a briefing package to capture. It is optional: clear ideas still go straight to capture; chart is for the oversized unclear ones. See Chart and the chart journeys in the cookbook.
Prototyping is the flagship because it is the most underused, but it is one member of a family. The shared shape is what matters: let something real answer the question, then capture the answer. The agent does the finding-out before a spec exists, and the spec records what was found rather than what somebody guessed.
| Route | The question it answers | Say something like |
|---|---|---|
| Prototype | How should this look or behave? Does this model survive the awkward cases? | “build three prototypes of this, let me react, then capture the winner as a spec” |
| Probe / measure | What is actually wrong, and where? | “run the load test against staging, then lock down a spec for the fixes the numbers point to” |
| Reproduce | Does the bug behave the way the report claims? | “reproduce this as a failing test, then capture a spec where that test is R1” |
| Eval / benchmark | Which of these actually wins on our data? | “evaluate the two variants on our fixtures, iterate until one clearly wins, then capture a spec to adopt it” |
| Research | What do we not know yet about the outside world? | “research how they price their plans, then capture a spec for a tiered pricing page - business requirements, not implementation” |
| Spike | How does this subsystem actually work? | “revert those changes and capture our discussion as a spec” |
| Bake-off in-spec | Which approach wins, when you cannot judge without building it properly? | “plan this with one task per candidate approach, plus a final task that compares them and keeps the winner” |
| Red-team the spec | What did we miss before writing a line of code? | “attack this spec for gaps and unstated assumptions before we plan it” |
Two notes on choosing between them.
Match the route to the question, not to habit. A performance complaint wants a probe, not a prototype. A “which library” argument wants a bake-off. A bug report wants a reproduction, and the reproduction becomes acceptance criterion R1 - the strongest spec opening there is, because the criterion is executable from the first minute. Reaching for the same route every time is how teams end up prototyping questions a measurement would have closed in ten minutes.
The agent can run most of these unattended. Research, probes, evals, and reproductions do not need a human watching, which makes them cheap to run before anyone has committed to a shape. The expensive human time then goes to reacting to real findings instead of speculating in a refinement meeting. Prototyping is the exception that genuinely wants a person in the loop, because reacting to the artifact is the work.
Every one of these lands in the same place: a spec whose claims trace to something that actually happened. The full catalog lives in the cookbook.
“It’s throwaway” is the default, not a law. Prototype code has three possible fates, and the plan stage decides which - not the person who wrote it, and not by reflex:
This is the moment that resolves the oldest friction on the team - product hands over something that works, and engineering has to decide whether it is a gift or a liability. Making it an explicit planning decision, with the architecture docs in context, turns that argument into a step.
Encode the rule rather than re-litigating it every time. A line in your CLAUDE.md/AGENTS.md is enough:
When seeding a spec from a prototype: treat the prototype as requirementsevidence, not as an implementation. The plan stage must state, per module,whether prototype code is kept, re-based on our standards, or discarded -checked against docs/architecture.md and the design-library rules.The context pack that priming builds for your repository - product strategy, target user, domain constraints, architecture, standards, design library - is not repo-only. Copy it into whatever prototyping tool the team uses, and the prototypes come back in your world instead of a generic one.
This matters more than it sounds. Product, business, and domain context rank with technical context, and most harnesses only carry the technical half. There is a large difference between an app used by a builder on a tablet on a site and one used by an analyst at a desk with two monitors - and an agent that was never told which one it is building will produce a competent, generic, wrong interface. Give it the product context and the same prompt produces something tuned to the actual user.
The same pack, copied into three tools, makes all three better. That is the cheapest quality win available to most teams.
When the interview asks something that feels obvious or stupid, the useful reaction is not to dismiss the questions and not to patch the prompt locally. It is: something is missing from the context surface, go fix it once.
A question that should not have needed asking is a measurement. It says the strategy doc, the domain notes, the ADRs, or the product context did not carry something a competent newcomer would need. Fix the document, and every future run - and every future human - benefits. Argue with the question, and you will answer it again by hand every sprint.
This is the discipline the workflow actually asks for, and it is the one most teams skip. It is also why context tends to live in three or four people’s heads on a struggling team: nothing ever forced the tacit knowledge into a durable form. The interview does.