How do I write a spec my team won't misread?

You want the spec to be so clear, so complete, that the team builds the right thing without ever needing to ask you a question. Examine that wish honestly. It is not a wish for clarity. It is a wish to avoid a conversation. No document is self-interpreting. Every sentence you write will pass through minds that don't share your assumptions. Some will misread it quietly and build the wrong thing with confidence. The spec did not fail — your trust in the spec alone failed. The actual job was never "write a flawless spec." It was always "get a team aligned on what to build." The document is a tool toward that. Used alone, it is a wish dressed up as a plan.

◆ How this problem reads on the two dials

GuidanceKnowledge

More coaching

Some to learn

1:1 with AureliusWith others (a Pod)

Some one-to-one

Practise with peers

The reframe is simple and quick to teach; the hard part is building the habit of talking it through, which takes coaching, not more explanation.

How the two dials adapt to you →

What’s really going on

You don't. No document survives contact with other minds unassisted. Writing the spec is half the job; the other half is talking it through with the people who'll build it. If you skip the conversation, you are trusting paper to do what only people can do.

🔒 What you’ll build togetherUnlock by starting

A moveBefore you write a word, get the team in a room and ask what they think the problem is. Compare answers out loud.

A moveAfter you draft the spec, don't send it and wait. Walk through it live with the people building it, section by section.

A moveAsk each person to say back, in their own words, what they'll build. Listen for the gaps, not the agreement.

A moveMark every place in the spec where you made a judgment call. Flag it, don't hide it. Judgment calls are where misreadings breed.

A moveAfter the build starts, check in early — not to inspect, but to catch a wrong turn while it's cheap to fix.

PractiseSay It Back · a Pod of 4 · 30 min

What changes unlock by starting

You stop treating a misbuilt feature as a writing failure and start treating it as a missed conversation.
Your team catches misunderstandings in a meeting instead of in production.
You spend less time perfecting prose and more time confirming shared understanding.
The team trusts the spec less and each other more — which is the correct order.

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.