🧾Writing Better Specs
Specs that ship: shorter, sharper, and structured around the questions engineers actually have.
Specs are how engineering interprets your judgment. A spec with ambiguous scope costs the team 2-3x the build time in clarifying questions, rework, and changed minds. Tight specs are a multiplier on engineering velocity.
A great spec is short, opinionated, and structured around the questions engineers actually ask: what's the user story, what are the edge cases, what's the success criterion, what's out of scope. If your spec answers those four cleanly, engineering can build from it without coming back for help.
The four questions engineers will ask anyway
When an engineer opens your spec, they're scanning for:
- What are we doing? User story, scope, the happy path.
- What about edge cases? Empty states, error states, what happens with a 4G mobile connection in India.
- How will we know it worked? Acceptance criteria. The thing that has to be true for QA to say 'ship it.'
- What's NOT in scope? Equally important — prevents engineers from building things you didn't ask for.
If your spec answers those four, you'll get fewer Slack pings.
The patterns that fail
- Vague verbs. "The system should handle invalid input gracefully." What does gracefully mean? Specify: "Show an inline error 'X' under the field; don't navigate away; preserve other field values."
- Hidden requirements. "Users should be able to share." But you didn't mention email vs. link vs. social. Each is a 2-day build. Enumerate.
- Missing edge cases. Specify: empty state, loading state, error state, max-length state. Every screen has at least 5 states; junior PMs design 1.
- Untested assumptions. "Users want X." How do you know? Cite the research or admit the assumption and design the spec to test it.
The spec / PRD division
A PRD answers why and what. A spec answers exactly what and how. Engineers usually want both — the PRD for context, the spec for build-from-able detail.
At many companies the PM writes both. At others the PM writes the PRD and a senior engineer writes the spec from it. Either is fine — clarify upfront who owns which artifact.
Modern spec writing
Increasingly PMs are writing specs collaboratively with the tech lead in real-time, often in Notion or Linear, rather than handing over a finished doc. The shared-doc pattern surfaces ambiguity faster than the throw-over-the-wall pattern.
Real-world examples
Linear popularized writing the spec directly in the issue tracker — short, focused, with the acceptance criteria as the first checklist. The team can comment, sub-issue, and iterate without leaving the tool. It works because the spec is tiny and the context is unified.
Go deeper — recommended reading
Interview questions (1)
Q1How would you handle an engineer pushing back on a spec saying 'this isn't possible in 2 weeks'?executionmid▼
Don't argue about whether it's possible — they know better than you. Ask three things:
- What's the longest pole? Surface the specific component that's blowing the estimate.
- What would v0.5 look like? Can we strip the most expensive 30% of scope and ship a leaner version that still tests the core hypothesis?
- What would it take to hit two weeks? If the answer is "headcount" or "removing dependency X," see if those are feasible.
The bad PM response is "but I promised this to the CEO." The good PM response is "OK, let's scope something we can actually do in two weeks that still moves the metric, and I'll re-pitch the larger version separately."