Requirements vs specs

A requirement states a needed capability or constraint ("user can reset password via email link valid for 30 minutes"). A specification details how you will implement it (API shapes, schemas, sequence diagrams). Product owns the former; engineering owns the latter — see design docs. Mixing them too early locks implementation before you understand trade-offs.

When PMs write API field lists into the PRD, they accidentally own the design. When eng starts coding from a vague one-liner, they accidentally own the product. Keep the seam clean; collaborate across it.

Writing requirements that survive contact with eng

Prefer observable behavior over adjectives.

When you need UI detail, link to designs rather than re-describing every pixel in prose — prose drifts; Figma (or equivalent) is the source for layout. The PRD still owns the rules behind the pixels: states, permissions, empty/error paths, and what is out of scope for this version.

Sequence that works

1. Discovery produces evidence the problem is real.
2. PRD / PR/FAQ locks problem, users, goals, non-goals, P0 behavior.
3. Eng design doc proposes architecture, APIs, data model, failure modes, rollout — alternatives considered, recommendation.
4. Tickets slice the approved design.

For PM–eng partnership norms, see working with PMs.

Spec smells

Watch for these in drafts (including your own):

• Solution in the problem statement
• Metrics that are outputs ("ship by June") rather than outcomes
• Empty non-goals
• Requirements that say "fast," "easy," or "intuitive" with no bar
• No instrumentation plan
• Open questions with no owners
• Scope that quietly includes three products

Fix smells before estimation. Prioritization on a fuzzy PRD just ranks confusion.

Common mistakes

• PRD as API spec. Product accidentally owns the design.
• One-liner tickets for a new surface. Eng accidentally owns the product.
• "Fast" and "easy" with no bar. Not testable, so not a requirement.

Check yourself

"Support SSO" in the P0 list. What's missing? Observable behavior: who can require which IdP, and what happens to password login.

Who writes the storage schema and auth checks? Engineering, in the design doc, after the PRD locks problem, users, goals and P0 behavior.

Key takeaways

• Requirements are observable behavior and constraints. Specs are implementation.
• Product owns the former; engineering owns the latter. Collaborate across the seam.
• Kill adjectives without bars, empty non-goals, and solution-in-the-problem before you estimate.

Further learning

Next: PR/FAQ when the customer narrative is the uncertain part. Working with PMs.