The Week the Prototype Beat the Spec

This is the story I open with when someone asks why I stopped writing specs first. It is small. It is one week. It changed how I work more than any framework I have ever read.

The short version

We had a feature stuck in review for three weeks: a twelve-page spec, four reviewers, and a debate that would not resolve because everyone was arguing about what a user would do and nobody knew. I stopped writing and built a clickable prototype in an afternoon with Claude Code, put it in front of five customers, and four of them reached for the wrong control first. The feature we had specced for three weeks was built around an interaction nobody used. The prototype did not win because it was better looking. It won because it produced evidence the spec could only guess at. When the cost of being wrong drops from three months of engineering to half a day, the spec stops being insurance and becomes an expensive way to keep arguing. I now build first and write the doc after, as a record of what we decided, not a bet we then defend.

The three-week argument

The feature does not matter, so I will keep it generic. Call it a smarter default: the product would look at what a user was doing and pre-fill the next step instead of making them choose from a menu. Everyone agreed it was a good idea. Nobody agreed on how it should behave at the edges.

So we wrote a spec. Then we reviewed the spec. Then we rewrote the spec. Twelve pages, four reviewers, three weeks. Every review meeting produced two new open questions for every one we closed. What happens when the guess is wrong? Do we show the menu anyway? Does the user correct it inline or start over? One reviewer wanted a confidence threshold. Another wanted an undo. A third wanted to A/B the whole thing before we committed.

Every one of those was a real question. Not one of them could be answered by the people in the room, because the people in the room already knew how the product worked. We were five experts arguing about what a confused newcomer would do, and none of us had been confused by this product in years.

That is the trap with the spec-first habit. A document is a place where opinions compound. Each round of review adds detail, and detail feels like progress, and none of it is evidence. We had produced twelve pages of increasingly confident guesses about a person who was not in the building.

The afternoon

I went home and stopped writing. I opened Claude Code and built the thing. Not a design, not a mock, a working clickable version with the smart default wired up and the menu behind it. About four hours. It was ugly. It did roughly one path well and fell over everywhere else, which was fine, because I only needed the one path.

The next morning I did the part that actually mattered. I put it in front of five customers. Not five stakeholders, five people who use the product to do their job and had never seen this feature. I did not explain it. I gave them a task and watched.

Four of the five reached for the wrong control first.

The smart default, the entire premise of the twelve-page spec, sat there pre-filled and correct, and four of five people ignored it and went hunting for the menu we were about to hide. They did not trust a value they had not chosen. The one interaction the whole feature was built around was the one nobody used, and the confidence threshold we had spent an hour debating was irrelevant, because the failure was not the model being wrong. It was the user not believing a model that was right.

You cannot get that from a doc. I have written a lot of specs, and I promise you I would never have written that failure mode into one, because it did not occur to me, because I already knew where the button was.

What actually ended the debate

I brought the recording of the five sessions to the next review. The meeting that had eaten three weeks lasted twenty minutes. Nobody defended their edge case, because the edge cases we had argued about were downstream of a premise that had just failed in front of us. We killed the auto-fill, kept a suggested value the user had to accept with one tap, and shipped a much smaller thing that tested clean the following week.

The spec was not wrong because we are bad at writing specs. It was wrong because it was a bet placed with no information, and we kept raising the stakes on the bet instead of buying the information. The information cost one afternoon.

This is the cost-of-being-wrong argument, and it is the whole game. When building a feature cost three months of engineering, a twelve-page spec was cheap insurance against an expensive mistake. You wrote the doc because being wrong in production was the most expensive thing that could happen to you. Now being wrong costs half a day. The math flipped. The spec is no longer insurance against an expensive bet. It is a slow, confident substitute for the cheap experiment that would settle the question.

What I do now

I did not stop writing things down. I stopped writing them down first.

The order changed. The prototype is the first artifact now. It is what gets reviewed, because it is the only thing in the room that a customer can actually touch. The eval is the contract: before I build, I write down how I will know it works, which for that feature was as simple as "the user accepts or corrects the suggestion without going to the menu." The doc comes last, and it is short, because most of what used to fill a spec was me hedging against uncertainty I can now just resolve. The doc is the receipt for a decision, not the argument for one.

The teams I have watched make this switch all describe the same thing: the meetings get shorter and the disagreements get smaller, because you cannot argue with a person reaching for the wrong button. The document was where we stored our confidence. The prototype is where we go to lose it, on purpose, while it is still cheap.

Try this week

Take the decision your team has been arguing about the longest. The one with the doc that keeps growing and the review that keeps not resolving. Do not write another word of it.

Build the smallest clickable version that exercises the one path you actually disagree about. An afternoon, not a sprint. Then put it in front of five people who do not already agree with you, give them a task, and say nothing. Watch what they reach for.

The argument you cannot win in a document usually dissolves the second a real person touches the thing. That is not a productivity trick. It is the cheapest way to be wrong that has ever existed, and being wrong early, in front of a customer, is the whole job now.