The Root Cause of Most Bad Builds

Ask any experienced engineer what the most common reason is that they end up building the wrong thing. The answer is almost always: "The requirements weren't clear."

Your job as a PM is to give your team enough clarity that they can make good decisions in your absence. Good specs allow work to continue without you needing to be a bottleneck.

The User Story Format

As a [type of user], I want [to do something] so that [I can achieve a goal].

"As a first-time customer, I want to reset my password via email so that I can regain access to my account without calling support."

The "so that" clause is the most important part — and the most commonly skipped. Without it, engineers have no context to make good tradeoffs when they hit ambiguous situations.

Acceptance Criteria: The Definition of Done

A user story without acceptance criteria is incomplete. Acceptance criteria are specific, testable conditions that define "done."

Format (Given / When / Then):

• Given a user on the login page, When they click "Forgot Password" and enter a valid email address, Then they should receive a reset email within 60 seconds.
• Given a user on the login page, When they enter an email address not in the system, Then they should see an error message that does not confirm whether the email exists (security requirement).

The second criterion captures a non-obvious edge case a developer might miss without explicit guidance.

What Goes in a Full Spec

• Problem Statement: What user problem are we solving? What evidence do we have this is real?
• Goals and Success Metrics: What does success look like? How will we measure it?
• User Stories / Scope: What are we building? What are we explicitly not building?
• Edge Cases and Constraints: What happens in the failure states? Any technical, legal, or business constraints?
• Open Questions: What do we not know yet that could affect the build?

Keep PRDs short. A two-page PRD that everyone reads beats a ten-page PRD that nobody does.

Common Mistakes in Requirements Writing

Writing solutions instead of problems: - Bad: "Add a blue button in the top right corner that says 'Upgrade.'" - Better: "Make it easier for freemium users to discover and initiate an upgrade to Pro."

Leaving acceptance criteria to imagination: - "The form should validate properly" → five different interpretations of "properly." Be specific.

Not including edge cases: - Happy path is not enough. Cover: empty state, error state, network failure, permissions issues, mobile vs. desktop behavior.

The "So What Happens When..." Test

Before handing off a spec, read through it and ask: "So what happens when...?" for every edge case you can think of.

• "So what happens when the user enters an invalid date format?"
• "So what happens when the API times out?"
• "So what happens if the user is on a mobile device?"

If your spec doesn't answer it, add it.

Key Takeaway: A great user story has a clear who, what, and why — with acceptance criteria specific enough that done is unambiguous. Cover edge cases. Keep specs short but complete. Write for the problem, not the solution.