The test of a PRD is not whether it reads well. It is whether two engineers who have never discussed the feature would build the same thing from it. Most PRDs fail that test, and the failure surfaces halfway through the sprint as a series of Slack questions that should have been answered in the document.
What makes a PRD unbuildable?
Four things, in order of how much time they waste. Each is detectable by reading the document before anyone starts work, which is the entire point of having one.
- It specifies a solution instead of a problem. 'Add a dropdown to the settings page' forecloses better options and hides the actual requirement.
- It uses unfalsifiable words. Fast, intuitive, seamless, robust. None can be built to or tested against.
- It omits the edge cases. What happens on empty state, on failure, on concurrent edit, for a user without permission.
- It has no acceptance criteria. Without them, 'done' is a matter of opinion and review becomes negotiation.
What sections does a buildable PRD need?
Six. Problem, users, scope, behaviour, acceptance criteria, and open questions. The open-questions section is the one teams skip and the one that most reliably prevents mid-sprint surprises, because it forces you to write down what you do not yet know.
# Bulk export for saved reports
## Problem
Users with 50+ saved reports currently export one at a time. Support sees
~12 tickets a month asking for a bulk option. Median session for these users
includes 7 sequential exports.
## Users
Analysts on Team and Enterprise plans with >20 saved reports (~340 accounts).
## Scope
IN: selecting multiple reports, exporting to a single zip, email on completion
OUT: scheduling, exporting to Drive/S3, changing the per-report format
## Behaviour
1. Selecting >1 report reveals a "Export selected" action.
2. Export runs async; the user is not blocked.
3. On completion, email with a signed link valid for 24h.
4. Limit 100 reports or 500MB per export, whichever is hit first.
## Acceptance criteria
- [ ] Selecting 0 reports leaves the action disabled.
- [ ] Exporting 100 reports produces one zip containing 100 files.
- [ ] Exceeding either limit shows the limit that was hit, before the job starts.
- [ ] A failed export emails the user and does not consume quota.
- [ ] The signed link 403s after 24 hours.
## Open questions
- Does an export count against the existing per-plan export quota? (owner: pricing)
- Do we need an audit log entry per bulk export? (owner: security)How do you write acceptance criteria that work?
Write each one as a statement that is unambiguously true or false after the feature exists. If a criterion needs a conversation to evaluate, it is not a criterion — it is a preference. The fastest check is whether a QA engineer could turn it into a test without asking anyone a question.
The ambiguity test
Before a PRD leaves your hands, search it for these words: fast, easy, intuitive, seamless, robust, scalable, user-friendly, appropriate, properly, handle. Every hit is either a number you have not decided yet or a behaviour you have not specified. Replace each one or move it to Open questions.
How much detail is too much?
Specify the behaviour and the boundaries; leave the implementation to the engineers. A PRD that names database columns has crossed the line — it constrains the solution without carrying the responsibility for it. A PRD that omits what happens when the export fails has not gone far enough.
Who should review a PRD before work starts?
At minimum one engineer who will build it and one person who will support it. The engineer catches unspecified behaviour; support catches the edge cases real users actually hit. A PRD reviewed only by other product people reliably ships with the same blind spots it was written with.
Frequently Asked Questions
How long should a PRD be?
Long enough to remove ambiguity, and no longer. A well-scoped feature is usually one to two pages. If it is longer than three, it is probably several features that should be split and shipped separately.
What is the difference between a PRD and a technical spec?
The PRD says what must be true for users and why; the technical spec says how it will be built. The same person can write both, but conflating them means the solution constrains the problem definition before anyone has questioned it.
Should a PRD include designs?
Link them, do not embed them. Designs change on a different cadence than requirements, and an embedded screenshot goes stale silently while a link stays current.
Who owns the PRD?
One named person, who is accountable for resolving the open questions. Shared ownership of a requirements document reliably produces unresolved ambiguity, because no one is responsible for closing it.
References
- API Design Guide — Google Cloud
- OpenAPI Specification — OpenAPI Initiative
- The Practical Test Pyramid — Martin Fowler
About Jishu Labs
Jishu Labs is a software development company founded in 2016. We build custom software, AI/ML systems, and full-stack web and mobile applications for clients, and we make eight AI tools for software teams.