Talk it through with Aurelius
Library›Aurelius›The problem
Aurelius · Work & Leadership
Knowledge + Guidance

Why can't my team ever write a spec clear enough to build from?

You keep rewriting the same spec. You add detail, close gaps, define edge cases — and still, someone builds the wrong thing, or asks a question the document should have answered. You conclude you're bad at writing specs. You are not. The spec is clear exactly as much as the decision behind it is clear, and not one bit more. If the team hasn't actually agreed on what success looks like, no amount of careful sentences will manufacture that agreement. You are asking a document to do the work of a conversation. So the fix is not a better template. It is sitting with the people involved, before you write anything, and forcing the decision into the open. Once that decision exists, the spec is just a record of it.

◆ How this problem reads on the two dials
GuidanceKnowledge
More coaching
A little to learn
1:1 with AureliusWith others (a Pod)
Some one-to-one
Practise with peers
The reframe takes one clear idea to teach, but fixing it requires repeated practice deciding with others before writing — so coaching carries most of the weight.
How the two dials adapt to you →
What’s really going on

The spec isn't the problem. You never decided what 'done' looks like — so the spec tries to invent the answer and describe it at the same time. That's why it stays fuzzy no matter how long you work on it. Stop writing. Gather the people who matter, name the decision out loud, and the words will come fast.

🔒 What you’ll build togetherUnlock by starting
A moveBefore writing a single line, ask everyone in the room: 'What does done look like, in one sentence?' If you get three different answers, you've found the real work.
A moveList every decision still unmade — scope, tradeoffs, what you will not build. Put a name and a date on each one. Decide them before you touch the document.
A moveWrite the spec only after the decision is made, never to discover the decision. If you catch yourself negotiating inside the document, stop and go talk to the person.
A moveWhen someone questions the spec later, ask whether they're questioning the words or the decision. Fix the right one.
A moveChoose one open question right now that you've been avoiding, and get an answer on it today.
PractiseName the Decision · a Pod of 4 · 30 min

What changes unlock by starting

  • Your team stops circling back to ask 'what did you actually mean by this.'
  • You write specs faster because you're recording a decision, not negotiating one.
  • Fewer meetings happen after the spec ships, because the real debate happened before.
  • You can tell the difference between 'the writing is unclear' and 'we haven't decided' — and you stop blaming your prose for the second one.

Related problems

One object, two jobs: a public answer to a real problem, and — the moment you start the chat — Aurelius’s live plan for your version of it.