A Written Spec for Every Feature — Because Minds Change Mid-Build

The failure mode this prevents

It always happens the same way. A feature is described in a call, everyone nods, development starts — and halfway through, the client's picture of the feature turns out to differ from ours, or their picture itself has evolved. Neither side is at fault: founders discover their product by watching it take shape, and that discovery is genuinely valuable. But when it collides with half-built code, the cost is real — rework, frustration, and the corrosive feeling on both sides that the other one 'changed the deal'.

We learned to treat this as a process problem with a process solution, not a discipline problem to blame on anyone. It became one of the defining lessons of our Invoice Guru engagement, and it now applies to every project we run.

What our specs actually look like

The word 'specification' suggests a forty-page document nobody reads. Ours are deliberately the opposite — usually a page or less, in plain language the client can actually evaluate:

• —What the feature does, described as what the user experiences — not as implementation
• —What it explicitly does not include, because scope is defined by its edges
• —The states that need an answer: empty, loading, error, offline, permission denied
• —Open questions, asked before code exists rather than discovered after
• —Sign-off from the client — a sentence of agreement, not a signature ceremony

Why it protects both sides

When an idea changes mid-development — and it will — the spec transforms the conversation. Instead of arguing about who remembers the call correctly, both sides look at a document and negotiate a change against it: what does the change cost, what does it delay, is it worth it now or in the next iteration? The change itself is welcome; the spec just makes its price visible before it's paid.

In hourly engagements this is also a fairness mechanism. The client sees what was agreed, what was delivered, and what changed en route — which is exactly the transparency that makes time-and-materials billing feel safe instead of open-ended.

Specs became more valuable in the AI era, not less

There's a twist we didn't anticipate: AI-assisted development has made written specs more valuable. A precise spec is, almost verbatim, a high-quality instruction for AI tooling — the clearer the specification, the more of the implementation can be accelerated safely. Teams that invested in the discipline of writing down what they're building are exactly the teams best positioned to hand parts of that building to AI.

The one-page spec, it turns out, was never bureaucracy. It's the cheapest artifact in software: the one that catches misunderstandings while they're still words.