Use this when: You've decided to build something and need to align the team on scope, goals, and success criteria before work begins.
You're done when: You have a one-page document that an engineer can estimate from, a designer can start sketching from, and a stakeholder can approve or challenge.
The Sequence
Breadboard before you polish
Before writing the full spec, sketch the idea as a breadboard. The concept comes from electronics: a breadboard is a prototyping board where you wire components together to test if the circuit works, without worrying about the final layout or casing. Ryan Singer adapted this in Shape Up as a way to think through features before any visual design happens.
A breadboard has three elements:
- Places — screens, pages, or locations the user can navigate to
- Affordances — the things users can interact with (buttons, fields, menus, links)
- Connection lines — the flows between places, showing what leads where
You draw these as simple boxes, words, and arrows. No colors, no layout, no UI. The point is to test whether the logic of the feature holds together. Does the flow make sense? Are there dead ends? Does the user have a clear path from start to finish?
If the breadboard doesn't work, no amount of visual polish will save it. If it does work, you've just written half your spec, because you now know the places, actions, and flows the feature requires. Paste the breadboard into your spec as the proposal section and you've given engineers and designers something concrete to react to without constraining the visual solution.
Sachin Rekhi makes a related point: prototypes are incredible, but they only address UX and functional requirements. They don't capture strategic context, competitive positioning, or success metrics. His recommendation is "a prototype plus a PRD" as the ideal unit of PM output. The breadboard or prototype shows how it works. The spec explains why you're building it, what you're betting on, and how you'll know it worked. Skip either half and the team is operating with incomplete information.
Separate the problem from the solution
Jackie Bavaro's spec process at Asana follows the Double Diamond model: two rounds of expansive thinking, one for the problem and one for the solution. The first milestone is reviewing goals and scope before touching the solution at all. This matters because most spec failures happen when teams jump to "what we're building" before agreeing on "what's actually broken." Asana's template enforces this by starting with Background, Problems, Goals, and Vision sections before a Proposal ever appears. If your team keeps debating solutions in spec reviews, the fix isn't better solutions. It's spending more time on the problem definition upfront.
Set the appetite, not the estimate
Traditional specs ask "how long will this take?" Shape Up flips the question: "how much time is this worth?" That's the appetite. Instead of estimating effort and accepting whatever timeline comes back, you decide upfront whether this is a 1-week small batch or a 6-week big batch. The appetite becomes a hard constraint, and the team shapes the solution to fit within it.
This changes how you write the proposal. Instead of describing the ideal solution and hoping it fits the timeline, you describe a solution that's deliberately scoped to the appetite. A 6-week appetite means you can build a full flow. A 1-week appetite means you find the simplest version that still delivers the core value.
Define acceptance criteria
Acceptance criteria describe exactly how a feature should behave, written in a format anyone can read. The standard structure is Given-When-Then (from the Gherkin language):
- Given a specific starting condition
- When the user takes an action
- Then the system produces this result
For example: Given a user is on the checkout page, When they click "Pay now" without entering a card, Then they see an inline error message below the card field.
This matters because it forces you to think through edge cases before engineering starts. It aligns PM, design, and engineering on what "done" means. And it gives QA a concrete checklist to test against. Write 3-5 acceptance criteria for each key flow in your spec.
Surface key technical decisions
Most spec failures aren't about missing features, they're about technical choices that got made implicitly during implementation. The checkout team picks a payment library on day one, then discovers it doesn't support the currency formats they need on day five. A key technical decisions section forces these choice points into the open before code is written.
There is no perfect solution, only tradeoffs. Every option gives you something and costs you something else. The job isn't finding the "right" answer, it's making the tradeoffs explicit so the team picks with eyes open. For each decision, lay out the options and what you gain and lose with each:
- Latency vs. cost — a real-time API call is fast for the user but expensive at scale. A batch job is cheap but adds delay
- Speed to ship vs. maintainability — the quick hack ships this week but becomes tech debt. The clean abstraction takes longer but the team can extend it in 6 months
- Security vs. simplicity — the locked-down approach adds friction for developers and users. The simple approach moves faster but may not pass a security review
- Build vs. buy — building gives you control and no vendor dependency. Buying saves months but locks you into someone else's roadmap and pricing
You don't need answers for every decision upfront. The point is naming the choice points and the tradeoffs for each option, so the team makes informed bets together instead of one engineer making an implicit choice the rest of the team discovers too late.
Common decision types: build vs. buy, which third-party API, monolith vs. service boundary, sync vs. async processing, where to store data, and which auth/permissions model to use.
Template
The spec is a service document, not a power move
Ken Norton, former Google PM, frames the PM role as servant leadership: "Bring the donuts." The spec exists to serve the team, not to demonstrate how smart you are. That means involving engineers before the spec is "done," not after. Norton's rule for working with engineers: never commit to scope without them, always explain the reasons behind decisions, and respect their time by being specific. A spec that surprises the team at a kickoff meeting has already failed. The best specs are co-authored in spirit, even if one person holds the pen. Share the rough draft early, absorb the pushback, and make the final version something the team feels ownership over.
Working Backwards
Amazon takes a radically different approach to specs. Instead of describing what to build, they write a fake press release for the finished product. This is mostly useful for big new features or new products, not for small improvements or bug fixes. Jeff Bezos introduced this "Working Backwards" process around 2004, and it's been used for every major Amazon product since, including Kindle, AWS, and Alexa.
The press release imagines a successful launch and captures the customer value in a single page. Then a FAQ section addresses both external questions (how does this help the customer?) and internal ones (what are the economics, risks, and challenges?). The team iterates on the PR/FAQ, sometimes for months, before writing a line of code.
Why it works: it forces you to articulate the customer benefit first, before you get lost in implementation details. If you can't write a compelling press release, the product probably isn't worth building. This pairs naturally with the spec template above. Write the PR/FAQ to test the idea, then write the spec to scope the build.
Working Backwards Template:
- Headline — one sentence announcing the product as if it's already launched
- Subheading — who it's for and the key benefit
- Problem paragraph — the customer pain in their words
- Solution paragraph — how the product solves it
- Getting started — how a customer begins using it
- Internal FAQ — economics, risks, dependencies, timeline
- External FAQ — pricing, availability, how it works
The rabbit holes section is where you call out the parts of the problem that look simple but could swallow the whole timeline. Technical unknowns, edge cases that seem small but aren't, integrations that could spiral. Naming them upfront tells the team: we know these exist, and we're choosing not to go down them. This is different from no-gos, which are adjacent features you're deliberately excluding. Rabbit holes are traps hiding inside the feature itself.
Example
A checkout team saw 15% drop-off at the payment screen. Their spec:
- Problem — 15% of users abandon at payment, support tickets mention confusion about pricing tiers
- Appetite — 1-week small batch, this is a scoping fix not a redesign
- Goal — reduce payment drop-off from 15% to 8%
- Proposal — simplify to one pricing summary, add inline explanations for each charge, remove the "compare plans" link that pulls users out of checkout
- Rabbit holes — don't attempt to dynamically calculate taxes inline (requires a tax API integration that's a 6-week project on its own)
- No-gos — not redesigning the full checkout, not adding new payment methods
- Acceptance criteria — Given a user is on the payment screen, When they view the pricing summary, Then they see a single total with inline explanations for each line item. Given a user clicks "compare plans," When the link is removed, Then they stay in the checkout flow
- Key technical decision — inline price explanations need a tooltip component. Option A: existing design system tooltip (ships in hours, team already knows it, but limited to plain text). Option B: custom popover (supports rich content and images, but 2 days to build and one more component to maintain). They went with A because the explanations were short text and shipping fast mattered more than flexibility
- KPI — payment completion rate
- KFI — fraud rate stays flat
The entire spec fit on one page. Engineering estimated it in 30 minutes. It shipped in one sprint.
Written with ❤️ by a human (still)