Tips for writing product specs that reduce engineering rework center on one insight: most engineering rework is not caused by bad engineering — it is caused by unclear requirements that were interpreted differently by the PM and the engineer building them.
The spec that prevents rework is not longer or more detailed. It is more precise about the three things engineers need: what done looks like, what the edge cases are, and what decisions have already been made.
Why Engineering Rework Happens
The four most common causes of engineering rework in product teams:
1. Acceptance criteria not written before development. The PM and engineer have different mental models of the feature. They discover the difference at demo, not at spec review.
2. Edge cases discovered during development. The spec covered the happy path but not what happens when the user does something unexpected. Engineering makes a guess; the PM disagrees at review.
3. Scope changes after development starts. A stakeholder sees the implementation in progress and requests a change. Engineering has to undo completed work.
4. Ambiguous terminology. The spec says "notification" and engineering builds an in-app notification. The PM meant an email. Neither was wrong — the spec was ambiguous.
H3: The Rework Audit
Before improving your spec process, audit your last 5 significant engineering rework events:
- What triggered the rework?
- Was the cause in the spec or discovered during development?
- What language in the spec led to the ambiguity?
The pattern across 5 events usually reveals 1–2 structural causes that the same spec improvements will address.
According to Lenny Rachitsky on his newsletter, the teams with the lowest engineering rework rates are the ones where the PM and lead engineer review the spec together before development starts — a 30-minute spec review that surfaces ambiguities before code is written prevents 3–5 hours of rework on average.
Tips for Writing Specs That Prevent Rework
Tip 1: Write acceptance criteria as user-facing assertions, not feature descriptions.
Feature description (bad): "Add a search bar to the dashboard." Acceptance criterion (good): "When a user types 3+ characters in the search field, results appear within 500ms. Results include [X, Y, Z]. No results state shows [specific text]."
Acceptance criteria that describe the user-observable behavior eliminate the interpretation gap between PM and engineer.
Tip 2: List every edge case you can think of before development starts.
For any input or action in your spec, ask:
- What happens if the input is empty?
- What happens if the input is too long?
- What happens if the user is in a limited permissions state?
- What happens if the data is missing or malformed?
- What happens on mobile vs. desktop?
Document your edge case list in the spec. For edge cases you haven't resolved, mark them as open questions with a deadline. Engineers who find unresolved edge cases during development will make a decision — and it may not match what the PM would have chosen.
According to Shreyas Doshi on Lenny's Podcast, the most common source of PM frustration in engineering reviews is unresolved edge cases that the engineer handled correctly given the spec but incorrectly given the PM's intent — the gap is always a missing specification, not a missing engineering judgment.
Tip 3: Define every term in the spec that could be interpreted multiple ways.
Create a terminology glossary for every spec where precision matters:
- "User" = logged-in user with an active subscription (not admin, not viewer)
- "Notification" = in-app notification in the notification center (NOT email)
- "Active" = has logged in within the last 30 days
One definition prevents one rework cycle.
Tip 4: Use concrete examples for every core behavior.
For every key interaction, provide a worked example with specific values: "When a user searches for 'proj' and has 3 projects named 'Project Alpha', 'My Project', and 'Prototype', the results should show all three in alphabetical order."
Tip 5: Lock scope before sprint starts — not after.
Scope changes after development starts are the highest-cost rework type. Implement a scope freeze at sprint planning: once a sprint starts, new requirements go to the next sprint.
According to Gibson Biddle on Lenny's Podcast, the spec quality improvement that produces the fastest rework reduction is the pre-sprint spec review — a 45-minute session where PM and engineering lead review the spec together and resolve all open questions before the sprint starts eliminates the mid-sprint surprise that causes the most expensive rework.
FAQ
Q: What is the most common cause of engineering rework? A: Acceptance criteria not written before development starts, causing PM and engineer to have different mental models of what done looks like that are only discovered at demo.
Q: How do you write good acceptance criteria for a product spec? A: Write user-observable behavior assertions: when user does X, system does Y, and the observable result is Z. Include specific values and edge cases. Avoid feature descriptions that can be interpreted multiple ways.
Q: How do you prevent scope changes during a sprint? A: Implement a scope freeze at sprint planning. Any new requirements discovered after the sprint starts go to the next sprint's backlog, not the current sprint. The PM is responsible for enforcing this boundary.
Q: How many edge cases should a product spec cover? A: All edge cases you can identify before development starts. Mark unresolved edge cases as open questions with a deadline. Don't assume engineers will resolve edge cases the way the PM would.
Q: What is a pre-sprint spec review? A: A 45-minute session where the PM and engineering lead review the spec together before the sprint starts to resolve ambiguities, surface edge cases, and align on what done looks like before any code is written.
HowTo: Write Product Specs That Reduce Engineering Rework
- Write acceptance criteria as user-observable behavior assertions before development starts — when user does X, system does Y, observable result is Z
- List every edge case you can identify in the spec — empty states, permission states, malformed inputs, mobile vs desktop — and mark unresolved ones as open questions with deadlines
- Create a terminology glossary for every term in the spec that could be interpreted differently — user, notification, active, and similar ambiguous words
- Provide a worked example with specific values for every core behavior so engineers have a concrete reference case, not just an abstract description
- Run a 45-minute pre-sprint spec review with the PM and engineering lead to resolve all open questions before the sprint starts
- Enforce a scope freeze at sprint planning so new requirements discovered after the sprint starts go to the next sprint rather than mid-sprint