Writing a PRD

Misalignment is expensive. A team that "kind of agrees" on a feature discovers the disagreement in code review, QA, or — worst — after launch. A PRD (product requirements document) exists to force clarity before that happens.

A PRD earns its keep when someone new can read it and answer: what problem, for whom, what does done look like, what must not break, and what are we deliberately skipping? If the doc cannot answer those, tickets will invent answers — inconsistently.

Docs do not replace conversation. They capture the decisions conversation produced. Skip forty-page templates nobody opens.

When you need a doc at all

• No doc: bugfix with clear repro; tiny copy change; well-understood chore inside an existing epic.
• One-pager: small feature with one persona and one success metric.
• Full PRD: cross-functional work, ambiguous requirements, or anything that will live in production for years.
• PR/FAQ: new product, new market, or a bet large enough that building the wrong thing would cost quarters.

The cost of under-documenting is rework. The cost of over-documenting is theater. Match weight to blast radius.

Sections that actually get read

Keep each short.

1. Problem and context. What hurts, for whom, how we know. Separate problem from solution — if the first paragraph is already "we will build a dashboard," rewrite it.
2. Users and jobs. Primary persona, secondary users, job to be done. "Admin configures SSO" is sharper than "enterprise customers."
3. Goals and metrics. One primary success metric, a few secondary, and guardrails you must not break. Tie to the north star when you can. pct_workspaces_with_shared_view_created_30d is a plan; "we'll look at engagement" is not.
4. Non-goals. The highest-leverage section. Adjacent requests you will refuse this version.
5. Requirements. User-facing behavior, ordered P0 / P1 / P2. Prefer outcomes and constraints over UI pixels unless design already decided.
6. Open questions and risks. Owners and dates. A PRD with zero open questions often skipped discovery.
7. Rollout and measurement. Flags, cohorts, events, kill switch, support playbook.

Write the non-goals and metrics first; if you cannot, you are not ready to spec.

Walking through saved views

A condensed structure you can steal:

Problem: Teams >20 re-apply the same filters dozens of
times a day; triage-owner activation is weak after week 1.

Users: Eng managers and triage owners (primary).

Goals: +15% WoW retention of "triage" among teams size 10+
within 6 weeks of GA. Guardrail: list p95 +<50ms.

Non-goals: Cross-project views; email digests of a view.

P0: Save filter+sort as a named private view; share with
the workspace; opening applies filters exactly.

Analytics: view_created, view_opened, view_shared.
Rollout: flag 10% → 50% → 100% over 2 weeks; kill switch.

An eng design doc then covers storage, auth and URLs — not the problem statement again.

Common mistakes

• Solution in the problem statement.
• Metrics that are outputs ("ship by June") rather than outcomes.
• Empty non-goals and no instrumentation plan.

Check yourself

First paragraph says "we will build a dashboard." What's wrong? Problem and solution are mixed. Rewrite until it names who hurts and what it costs them today.

Tiny copy change. Write a full PRD? No. Match weight to blast radius. A full PRD for a two-week tweak is bureaucracy.

Key takeaways

• A PRD aligns teams on problem, users, metrics, non-goals and P0 behavior before code.
• Non-goals and open questions are as important as the feature list.
• Right-size the doc to the bet. Write metrics and non-goals first.

Further learning

Next: requirements vs specs. Map: PRDs and specs.