Write Spec
When to use
Use this when a feature is ready to move from idea to build and you need a document that aligns design, engineering, and stakeholders on what you are building, why, and how you will know it worked.
Not for: early idea exploration (use pm-brainstorming), a lightweight status note (use pm-stakeholder-update), or dictating implementation details that belong to engineering. If the problem is still unvalidated, do research first, do not spec a guess.
Method
- State the problem and context: who has it, evidence it matters, why now. Ground in data or research, not assertion.
- Define goals and non-goals explicitly. Decision point: for every tempting scope addition, decide goal or non-goal, non-goals prevent creep and matter as much as goals.
- Specify success metrics: the primary metric proving it worked, plus guardrails that must not regress, each with target and measurement window.
- Describe the solution: user stories, key flows, and states (empty, error, edge). Enough for engineering to estimate without dictating how to build it.
- Write acceptance criteria as testable statements (Given/When/Then or clear pass conditions). These are the definition of done.
- Cover the rest: dependencies, risks, open questions, rollout and instrumentation plan.
Example
Problem: 30% of users never complete profile setup (source: funnel data). Goal: raise setup completion to 60%. Non-goal: redesigning the whole settings area. Primary metric: setup completion rate; guardrail: no drop in day-7 retention. Acceptance criterion: "Given a new user on the setup screen, When they skip an optional field, Then they can still reach the dashboard." Rollout: 10% flag, watch completion for one week.
Pitfalls
- Asserting the problem matters with no data or research behind it.
- Omitting non-goals, inviting scope creep mid-build.
- Success metrics with no target or window, so "worked" is unfalsifiable.
- Over-specifying implementation, stepping on engineering's design space.
Output format
# Spec: [feature] — [date] — [status: draft/review/approved]
Summary & problem statement (with evidence).
## Goals / Non-goals
- Goals: ...
- Non-goals: ...
## Success metrics
- Primary: [metric] — target — window
- Guardrails: [metric must not regress]
## Solution
- User stories, key flows, states (empty/error/edge)
## Acceptance criteria (testable)
- Given/When/Then ...
## Dependencies, risks, open questions
- ...
## Rollout & measurement plan
- ...
Open questions stay visible, not papered over.
1---2name: pm-write-spec3description: Write a PRD or feature spec that aligns design and engineering — problem with evidence, explicit non-goals, measurable success metrics, and testable acceptance criteria.4---56# Write Spec78## When to use9Use this when a feature is ready to move from idea to build and you need a document that aligns design, engineering, and stakeholders on what you are building, why, and how you will know it worked.1011**Not for:** early idea exploration (use pm-brainstorming), a lightweight status note (use pm-stakeholder-update), or dictating implementation details that belong to engineering. If the problem is still unvalidated, do research first, do not spec a guess.1213## Method141. State the problem and context: who has it, evidence it matters, why now. Ground in data or research, not assertion.152. Define goals and non-goals explicitly. **Decision point:** for every tempting scope addition, decide goal or non-goal, non-goals prevent creep and matter as much as goals.163. Specify success metrics: the primary metric proving it worked, plus guardrails that must not regress, each with target and measurement window.174. Describe the solution: user stories, key flows, and states (empty, error, edge). Enough for engineering to estimate without dictating how to build it.185. Write acceptance criteria as testable statements (Given/When/Then or clear pass conditions). These are the definition of done.196. Cover the rest: dependencies, risks, open questions, rollout and instrumentation plan.2021## Example22Problem: 30% of users never complete profile setup (source: funnel data). Goal: raise setup completion to 60%. Non-goal: redesigning the whole settings area. Primary metric: setup completion rate; guardrail: no drop in day-7 retention. Acceptance criterion: "Given a new user on the setup screen, When they skip an optional field, Then they can still reach the dashboard." Rollout: 10% flag, watch completion for one week.2324## Pitfalls25- Asserting the problem matters with no data or research behind it.26- Omitting non-goals, inviting scope creep mid-build.27- Success metrics with no target or window, so "worked" is unfalsifiable.28- Over-specifying implementation, stepping on engineering's design space.2930## Output format31```32# Spec: [feature] — [date] — [status: draft/review/approved]33Summary & problem statement (with evidence).3435## Goals / Non-goals36- Goals: ...37- Non-goals: ...3839## Success metrics40- Primary: [metric] — target — window41- Guardrails: [metric must not regress]4243## Solution44- User stories, key flows, states (empty/error/edge)4546## Acceptance criteria (testable)47- Given/When/Then ...4849## Dependencies, risks, open questions50- ...5152## Rollout & measurement plan53- ...54Open questions stay visible, not papered over.55```
Matrixx0070