Write the spec first, then debate it.
"Create product specs that define what to build, what to skip, and when a spec is done."
Why this exists
Engineers build what you write, not what you meant. A spec closes this gap. Prototyping without a spec is not a plan; it is a bet that everyone has the same picture in their head, which they rarely do.
Operational Flow
Write the problem statement: Limit it to one paragraph. Explain what is broken, for whom, and what evidence supports it. If you cannot write this paragraph, you are not ready.
Propose the solution: Focus on behavior, not implementation details. For example, explain that a button does a specific action, rather than detailing the React component and API calls.
Define what is out of scope: Explicitly list what this spec is not solving. This section prevents scope creep mid-sprint.
Define success criteria: State what winning looks like and how to measure it. Name the metric, baseline, and target.
List open questions: Document anything you do not know yet that could change the solution. Assign every question to an owner with a deadline.
Identify edge cases: Document at least three conditions that could break the happy path. If you cannot list three, you have not analyzed the problem deeply enough.
Review the spec: Share the document in Notion with an engineer and a designer before coding. Incorporate their objections.
What good looks like
- A spec receives feedback asking what happens when the user is offline, proving the reviewer analyzed the document carefully.
- An engineer keeps the spec open in a tab and references it two weeks into building.
- A spec has a short out of scope section because the author made difficult calls about what to exclude.
What NOT to do
- Don't describe the UI in pixel-level detail while failing to explain why the feature exists.
- Don't treat the spec as finished when you stop writing. It is only done when the team reviews it and raises no further objections.
- Don't skip the open questions section because you are embarrassed about not knowing the answers yet.
- Don't write the spec after engineering work has started. At that point, it is documentation, not planning.
Writing a spec is a forcing function because the act of writing reveals what you do not understand. The year we lost three weeks reworking an onboarding flow, the post-mortem showed a single root cause. Nobody had defined what onboarding complete meant. Engineering and product built different things, and the client signed off on Figma mockups that matched neither. Writing the spec would have taken an afternoon, but the rework took three weeks and an awkward client call.
Keep specs short. A good spec fits on one page. If yours runs to five pages, you are writing an essay to avoid making a decision. The test is whether a new engineer can read the spec and build the correct feature without asking you questions. If that seems unrealistic, rewrite the problem statement until it is crisp. Everything else follows from there.