Hand three engineers the same paragraph describing a feature and you get three different features. Not because anyone is careless. Prose is ambiguous by nature. “The list should update in real time” contains at least four decisions nobody made, and each reader makes them differently, confidently, in private. You find out at review, which is the most expensive possible moment to discover that the spec meant three things.
Hand those same three people a working prototype and the ambiguity collapses. “It should look like this, behave like this, respond like this when you do that.” There is nothing to interpret, because the prototype is not a description of the behavior. It is the behavior. A spec you can misread; a running thing you cannot.
Why prose can’t pin behavior down
A specification written in words is a compression of an interactive experience into a linear string, and the decompression happens in the reader’s head. Every gap gets filled with an assumption, and the assumptions are invisible until they collide. “Real-time updates” leaves the reader to decide the latency, the behavior on conflict, what happens offline, whether a partial update is worse than a stale one. The words are the same for everyone. The product each person builds from them is not.
This was always a tax. You paid it in clarification meetings, in rework, in the slow discovery that “done” meant different things to the writer and the builder. Teams learned to write more carefully, add acceptance criteria, attach mockups, and it helped at the margins. It never solved the core issue, which is that prose cannot fully specify an interactive thing. There is always a gap between the description and the experience, and the gap is where the wrong product gets built.
Building got cheap enough to specify by building
Here is what changed. A specification used to be cheaper to write than the thing it described, which is the entire reason we wrote specs instead of just building. You could not afford to build three versions to find out which one you meant. So you described, argued about the description, and built once.
That economics inverted. When an agent turns an idea into a working prototype in an afternoon, the prototype is no longer meaningfully more expensive than the paragraph. And the prototype answers questions the paragraph can only gesture at. You do not describe the interaction and hope it lands. You build it, look at it, feel that the timing is wrong, and fix it, and now the spec is the corrected interaction. This is the practical face of building getting cheap and deciding getting expensive: when construction is nearly free, the most precise way to say what you want is to construct a small version of it.
What a prototype-as-spec actually pins down
A prototype is not just less ambiguous in a vague, feel-good way. It nails down specific things that prose reliably fumbles:
- Interaction and timing. What responds instantly, what shows a loading state, what animates, what feels wrong at 300ms and right at 120ms. You cannot write this precisely. You can only build it and feel it.
- State and edge behavior, made visible. The empty state, the one-item state, the too-many-items state. In prose these get a sentence each if you are diligent. In a prototype they exist or they do not, and their absence is a visible hole instead of a silent gap.
- The shape of the thing. How the pieces sit together, what is primary, what is buried. Layout decisions that take paragraphs to describe badly are obvious in one glance at a working screen.
- The boundary of the idea. This is the underrated one. Building a prototype forces you to hit the edges you hand-waved past. The moment you have to make the button do something, you discover the decision you had been avoiding.
That last point is the real gift. A prose spec lets you stay vague exactly where it matters, because words tolerate vagueness. A prototype does not. It makes you decide, because a running thing has to actually do something at every point you were planning to figure out later.
The limits, said plainly
A prototype is a spec for how it behaves. It is a bad spec for several things, and pretending otherwise is how you get burned:
- It does not say why. The prototype shows the decision, not the reasoning behind it. Six weeks later, someone asks why the flow works this way and the prototype cannot answer. The interaction is pinned; the intent behind it evaporated unless you recorded it separately.
- It does not capture the non-functional contract. How fast under load, what happens at scale, the security boundary, the failure modes under real traffic. A prototype that works for one user on your machine says nothing about the thing that has to hold for ten thousand.
- It quietly implies decisions you never made. Every prototype makes a thousand incidental choices, this color, that copy, this ordering, and a reader cannot tell which were deliberate and which were the tool’s defaults. The prototype specifies everything with equal confidence, including the parts you did not mean to specify.
That last limit is the dangerous one, and it is the same trap as a prototype quietly becoming the product. A prototype meant to pin down an interaction gets treated as a decision about everything it happens to contain. The fix is not to distrust prototypes. It is to be explicit about what the prototype is specifying and what is just scaffolding, so the accidental choices do not get promoted to requirements by default.
Prototype plus the decision behind it
The resolution is not prototype versus written spec. It is prototype for the behavior, plus a thin record of the intent and the boundaries. The prototype answers “what exactly does it do,” which prose does badly. A short written decision answers “why, and what must hold, and which parts here are load-bearing versus incidental,” which the prototype does not answer at all, and unlike the prototype that written decision is portable across tools.
Together they are a complete spec that is hard to misread. The interaction is nailed by the running thing. The reasoning and the constraints are captured next to it, so the prototype does not have to carry meaning it cannot hold. Neither alone is enough. The prototype without the intent is a decision with no memory of why. The intent without the prototype is the ambiguous paragraph you started with.
Where PaellaDoc fits
This is the pairing I am building PaellaDoc around. A prototype should not float free as an artifact whose meaning nobody can reconstruct in a month. It should be connected to the decision it embodies and the constraints it has to respect, so that what the prototype specifies about behavior and what you decided about intent live as one thing. The interaction is unambiguous because it runs. The reasoning survives because it is recorded next to it, not left to evaporate.
Stop writing paragraphs that three people will read three ways. When building a small version is nearly free, build it, and let the running thing carry the part of the spec that words were always going to get wrong. Then write down the why. The prototype is impossible to misinterpret. Just make sure you also said what it was for.
Frequently asked questions
Can a prototype replace a written spec?
For behavior, yes, and better. A prototype is not a description of the interaction, it is the interaction, so it cannot be read three ways. It pins timing, state and edge behavior, and layout, the things prose reliably fumbles. But it only replaces the part of the spec that says what the product does. The reasoning and the constraints still need a written record.
What can a prototype not specify?
Three things. It does not say why the flow works this way, only that it does, so the intent evaporates unless you record it separately. It does not capture the non-functional contract: performance under load, scale, security, failure modes. And it quietly implies a thousand incidental choices, colors, copy, ordering, that a reader cannot tell apart from the deliberate ones. It specifies everything with equal confidence.
Do I still need a written spec if I have a prototype?
Yes, a thin one. The prototype answers “what exactly does it do,” which prose does badly. A short written decision answers “why, what must hold, and which parts here are load-bearing versus incidental,” which the prototype cannot answer at all. Together they are a complete spec that is hard to misread. The prototype without the intent is a decision with no memory of why.
How do I stop a prototype from being read as final decisions?
Be explicit about what it is specifying and what is just scaffolding. A prototype makes a thousand incidental choices and presents them all with the same confidence, so a reader promotes accidental defaults to requirements unless you say otherwise. Pair the running thing with a short note on which parts are load-bearing and which are placeholder, so the boundary is stated, not guessed.