Writing a Product Spec

What a product spec contains

A well-formed product spec has five components.

The user problem, stated in one paragraph. Not a feature request — a description of what's broken for the user right now, from their perspective. "When a teammate leaves a comment on a spec, the author doesn't find out until they happen to re-open the document. Comments go unread for days. The feedback loop that makes collaboration valuable is broken by latency."

The outcome you're optimizing for. Not a feature list — an observable change in behavior. "Authors respond to comments within 4 hours instead of 3 days" is an outcome. "Add a notification bell icon" is a feature. Features serve outcomes. The spec should lead with the outcome so the agent knows what tradeoff to make when implementation gets hard.

Success criteria that a human can verify. These become the acceptance tests. They should be concrete enough that someone watching a screen recording could confirm them. "The user receives a notification" is too vague. "A badge appears on the inbox icon within 5 seconds of a new comment" is testable. Aim for 3–7 criteria.

Scope boundaries. What this intentionally does not cover, and why. Scope boundaries prevent the agent from gold-plating. If you don't mention that email notifications are out of scope, the agent might build them because they seem like a natural extension.

Decisions you've already made. If you've decided to use WebSocket push instead of polling, say so. These become locked decisions that the agent will not reopen without asking.

What a product spec does not contain

No architecture. No file paths. No database schemas. No component names.

The product spec is technology-agnostic on purpose. It describes the what and why at a level where a designer, an engineer, or a PM could all read it and agree on the same thing. Architectural decisions belong in the technical spec, where they can be grounded in the actual codebase.

Worked example

The following is a complete product spec for a notification feature.

Problem:
When collaborators leave feedback on spec documents, the author doesn't
learn about it until they manually re-open the file. This creates
multi-day feedback loops that undermine real-time collaboration.

Outcome:
Authors are aware of new comments within minutes, not days, and can
respond without context-switching away from their current work.

Success criteria:
1. A visual indicator appears on the inbox icon within 5 seconds of a
   new comment on any document the user authored or is mentioned in.
2. Clicking the indicator shows the comment in context — the user sees
   the highlighted text and the comment thread without navigating to
   the document.
3. The indicator clears when the user has viewed the comment. Viewing
   is sufficient.
4. Comments on documents the user does not own are not sent as
   notifications.

Not in scope:
Email or push notifications. Notification preferences or muting.
Comment resolution workflows.

Decided:
Notifications are ephemeral — viewing clears them. No persistent
history in v1.

Notice what this spec does not say: no mention of WebSockets, Postgres tables, React components, or file paths. Those belong in the technical spec. The product spec hands the agent a problem statement, a measurable outcome, and a clear boundary — nothing more.