The Ugly Spec

The brief is pretty.

That is the problem.

It has nice words.

Strategic. Clean. Simple. Agent-ready. Customer-first. Built for scale. All the little candles ambitious people light when they want the room to smell like progress.

Then someone tries to build from it and the spell breaks. The designer asks what happens on the empty state. The developer asks which action is allowed to fail. The agent asks for tools you never meant to give it. The contractor sends back exactly what you requested and somehow not at all what you wanted.

Now you are irritated. Not because the work is hard. Because the work found the fog you were hoping nobody would notice.

The False Diagnosis Is Execution

This is the part where smart builders blame execution. The freelancer did not get it. The agent was too literal. The no-code tool was too limited. The team lacked taste. The market moved. The stack was wrong.

Sometimes that is true. Some people can ruin a clear brief with astonishing speed. Some tools really do collapse the minute the work stops being a tutorial. Some agents behave like a bright intern who has read every book and never seen a customer leave angry.

But there is another diagnosis, and it stings because it moves the blame back into the room.

The spec was not ugly enough.

Not detailed in the theatrical, enterprise, binder-on-a-shelf way. I do not mean a document so swollen it needs its own onboarding session. I mean ugly in the useful sense: blunt, testable, specific, narrow, unromantic, and full of the little decisions you would rather keep in your head.

A pretty plan says, "Make onboarding feel effortless." An ugly spec says, "A new user with no imported data must understand the next action in under ten seconds, without reading a help article, and the product must not ask for calendar access until after the first saved outcome."

One makes you sound tasteful. The other makes the work possible.

The Market Cannot Build From Your Mood

The private version of the idea feels complete because your brain keeps filling in the blanks. You see the missing screen. You hear the voice. You know which edge cases are absurd. You know what "premium" means, what "simple" excludes, and which tradeoff matters more when the buyer is tired.

Lovely. None of that has left your skull.

That is why vague work flatters the person who owns it and punishes everyone downstream. The founder feels sophisticated because the idea still has infinite range. The builder feels trapped because every implementation choice becomes a hidden personality test. The customer feels the blur because the product keeps asking them to supply context the creator never had the nerve to choose.

This is not only a software problem. It happens in offers, sales pages, content systems, onboarding flows, hiring briefs, AI workflows, and little operational fixes that live too long as vibes. You ask for "better follow-up" and get more pings. You ask for "thought leadership" and get beige paragraphs with a LinkedIn haircut. You ask an agent to "handle support" and then act shocked when it cannot infer the social cost of a wrong answer.

The market is not cruel because it rejects your intention. It is cruel because it only gets to touch what you actually made legible.

Specification Is Coming Back With Teeth

The funny thing about the current AI moment is that everyone wants powerful tools until the tools ask for a clear world. Then suddenly clarity feels like paperwork.

It is not paperwork. It is infrastructure.

Look at The Website Specification, a public project that lays out the technical features a decent website should have across standards, accessibility, security, privacy, resilience, performance, and agent readiness. The interesting part is not that someone made a checklist for the web. The interesting part is the relief. A good spec removes the need to keep re-litigating what "done properly" means.

It gives the work a spine.

This matters more as agents move from answering questions to taking actions. Google Cloud describes the agent shift as software that can understand a goal, create a multi-step plan, and act on your behalf under guidance and oversight in its 2026 AI agent trends report. That phrase should sober you up. If the system can act, your vague intention is no longer harmless. It becomes an instruction with legs.

The old cost of a weak spec was drift. The new cost is drift with tool access.

The operator who wins now is not the one who writes the longest prompt. It is the one who can make the work unambiguous enough for judgment, tools, and proof to share the same room without pretending they are the same thing.

The Spec Is Where You Stop Lying

Most ambitious people do not avoid specs because specs are difficult. They avoid them because specs remove the soft blur around identity.

As long as the idea is broad, you can still be the person building the elegant platform. The serious founder. The strategic operator. The one who sees a bigger game. Once the ugly spec arrives, romance starts losing furniture.

Who is this for?

What exact moment does it change?

What does it refuse to do?

What proof tells us it worked?

What failure should stop the system before it gets clever?

These questions are rude in the best way. They make it harder to hide inside scale language. They turn "AI-powered productivity" into a specific repeated task with a before, an after, a boundary, and a human consequence. They turn "premium service" into a response standard, a bad-fit rule, a handoff, and a visible receipt. They turn "content strategy" into one audience, one wound, one proof object, one distribution surface, and one next action.

This is why the ugly spec feels like a demotion. It takes the grand private movie and forces it into a scene small enough to shoot.

Good. The scene is where money can enter.

Joel Was Right About the Desert

Joel Spolsky wrote years ago that skipping specs is treated like saving time, then compared it to crossing the Mojave with only the clothes on your back in his argument for painless functional specifications. The metaphor is old. The disease is not.

The modern version has better tools and the same arrogance. You open a blank file, call the project obvious, and assume momentum will reveal the missing decisions later. It does reveal them. Just not kindly.

A missing user definition becomes confused positioning. A missing bad fit rule becomes a customer you should never have served. A missing stop condition becomes an agent that keeps going because nobody told it where judgment had to enter. A missing proof standard becomes a launch that feels successful because people were nice in public and silent with their wallets.

The spec would have made those failures smaller. Not gone. Smaller. That is the mercy.

Specs do not remove uncertainty. They stop you from spending uncertainty in the most expensive place.

Build the Ugly Spec

Do not start with the perfect template. Templates are dangerous when they let you feel complete before you have made a choice. Start with the work that would make a tasteful person slightly uncomfortable.

Write the user in a way that excludes people. Not "busy professionals." Say the actual person in the actual moment. A solo consultant after a referral call. A customer success lead with a red renewal account. A technical founder who retreats into the repo when the sales page needs a decision.

Write the scene. Not the category. The scene is where the pain has furniture. The inbox at 11:18. The checkout page after the shipping surprise. The dashboard after the first failed import. The support reply when the buyer has already tried the obvious fix.

Write the before and after in behavior. Not "they feel confident." What do they do differently? What gets sent, saved, paid, approved, cut, escalated, or understood? If the outcome cannot survive a verb, it is probably still a mood.

Write the boundaries. This is where amateurs get precious. They want the thing to do everything because exclusion feels like lost upside. Exclusion is not lost upside. It is how the work stops pretending.

Write the bad-fit rule. A serious product knows who should not use it. A serious service knows which client turns the machine into soup. A serious agent workflow knows which task must stop and ask for a human.

Write the proof. Not praise. Proof. What has to be true in the world after this works? A shorter handoff. A replied email. A cleaner data row. A paid invoice. A customer who can repeat the promise without your rescue paragraph.

Write the stop rule. The moment the work crosses money, privacy, legal risk, customer trust, or live production, do not let ambition improvise. Give the system a clean place to pause. The stop rule is not pessimism. It is how leverage survives contact with consequences.

Ugly Does Not Mean Bloated

There is a bureaucratic version of specification that deserves every insult it gets. It turns uncertainty into page count. It hides cowardice inside ceremony. It makes the work pass through so many approvals that nobody can remember the customer by the time the file reaches the meeting.

I am not defending that.

The ugly spec is lean because it is honest. It has no interest in impressing the organization. It wants to remove translation tax. It wants the builder to know what matters. It wants the agent to know where not to act. It wants the buyer to encounter a thing made by someone who chose instead of gestured.

The efficient move is to skip the spec and start making assets. The effective move is to write down the decisions that will otherwise leak through every asset you make.

You are not slowing down the work. You are preventing the expensive kind of speed, the kind where everyone moves quickly in a slightly different direction and calls the collision learning.

Hand It to Someone Else

The test is simple. Can someone else use the spec without borrowing your brain?

Not perfectly. Perfect handoff is a fantasy sold by people who have never watched two smart adults define "done" differently in the same meeting. The standard is cleaner: does the spec reduce the amount of missing judgment the next person has to invent?

If the answer is no, keep going. Add the boundary. Add the non-example. Add the failed case. Add the exact user scene. Add the proof standard. Add the stop rule. Remove the adjective that makes you feel tasteful and replace it with a condition someone can verify.

Then hand it to the builder, the contractor, the colleague, the agent, or the part of yourself that will wake up tired next Tuesday and try to remember what mattered.

The work changes when it can leave your head without becoming softer. That is the whole game. Not more notes. Not more tools. Not another little cathedral of planning. A spec ugly enough to carry judgment across distance.

That is when the brief stops being pretty.

It becomes usable.