Every product has a specification somewhere. The question is whether it’s a document someone wrote before building, a document someone wrote after to explain what got built, or just a vague shared understanding that turns out not to be shared at all.

Most specs are one of the last two. Builders know this. It’s why “spec” has become a slightly ironic word in a lot of technical communities — a thing that nominally exists, gets referenced in meetings, and then diverges silently from reality the moment someone opens a code editor.

But the problem isn’t specs. It’s a specific failure mode that happens long before the first line of code.

Specs fail when they’re written to describe a solution rather than a problem.

A solution-spec sounds like: “The user will click a button labeled ‘Upload’ which opens a file picker allowing selection of PDF and DOCX files, which are then stored in S3 and indexed for search.”

A problem-spec sounds like: “An analyst has 50 documents from a data room. She needs to find every mention of environmental liability across all of them in under ten minutes, with enough context to know if each mention is significant.”

The first type is easy to write and feels productive. You’re building something specific. You can check boxes. You can estimate time.

The second type is uncomfortable because it exposes how much you don’t know. What counts as “significant”? What if she has 500 documents? What if the mentions span multiple files? What if the terminology varies by deal?

But the second type is the one that produces a product that works. The first produces a product that matches its spec and misses its users.

The test for a good spec is whether it can be used to judge a finished product.

Hand the spec to someone who wasn’t part of building the product. Ask them: does this solve the problem described? If the spec describes a button and a file picker, they’ll say yes the moment the button exists. If the spec describes an analyst finding environmental liability mentions in ten minutes, they’ll actually run that scenario.

One of these tests catches problems. The other catches typos.

There’s a related failure mode at the other end: the spec that’s so thorough it becomes the product.

These are the 40-page specs that live in Notion or Confluence or wherever your team stores things that get referenced once and then forgotten. The ones that describe every edge case before you’ve validated the core use case. The ones that feel like progress because writing them is work, and work feels like building.

The spec isn’t the product. It’s the contract between the problem you’re solving and the product you’re building. Like any contract, it should be as short as it can be while still covering what matters.

The spec that ships has one property that the others don’t: someone read it before building anything, agreed that solving it would be valuable, and then built toward it instead of away from it.

That’s it. The rest is craft.