Write· Mixed

Write a product spec for a feature that ships

9-step playbook for writing a feature spec that engineering can start on Monday with zero open questions and no surprise scope.

Open in DockPMs and founders writing PRDs

Most feature specs fail one of three ways: they describe behavior without describing the user (no problem statement), they describe the user without describing behavior (no acceptance criteria), or they leave the open questions inside the author's head. This playbook walks the 9 sections that ship: problem, users, success metric, scope and non-scope, user stories with acceptance criteria, design and data, rollout, risks, and the open-questions log. Each section comes with the agent prompt that drafts it from your scrappy notes.

Outcome

A feature spec engineering can start on Monday morning with zero open questions, a single owner per ambiguous decision, and an acceptance test that closes the loop on whether it shipped right.

Time1-3 days of focused writing, plus 2-5 days of reviewDifficultyintermediateForPMs, founders, and tech leads writing feature PRDs.

What you'll need

Pre-register or install before you start.

LinearFree for up to 10 users, $8/user/mo Standard

File the spec as an issue + link the engineering subtasks underneath.

FigmaFree tier, $15/editor/mo Professional

Wireframes and design references the spec links to.

LoomFree for 25 videos, $15/creator/mo Business

Record a 5-minute walk-through of the spec for async review.

Notion or DockFree tier, $19/mo Pro on Dock

Host the spec doc itself, with comments and a versioned history.

The template · 9 steps

Top to bottom. Each step has tasks, pointers, gotchas.

Write the problem statement (one paragraph, no solution)

1-2 hr if you have research, half a day if you don't

The first paragraph is the spec's most important sentence. It describes the user's actual problem, in the user's actual language, without proposing a solution. If you can't write it without saying 'add a button' or 'build a dashboard', you don't understand the problem yet. Go talk to three users.

Tasks

List 3 users you've talked to about this problem in the last 30 days
Write a single paragraph: who has the problem, what they're trying to do, what's currently broken
Cut every word that proposes a solution
Read it back: does it describe the user's world, or your product's world?

Pointers

GuideMarty Cagan: product discovery GuideTeresa Torres on opportunity solution trees

Gotchas

If your problem paragraph could apply to any product in your category, it's too generic. Specifics make engineering scope decisions easier.
Don't paste user quotes verbatim into the problem section. Paraphrase. Quotes go in the Pointers table.

Agent prompt for this step

Read the user's notes (chat transcript or pasted notes) and draft a 1-paragraph problem statement.

Constraints:
- 60-120 words.
- No mention of buttons, screens, or solutions.
- Use the language users used in their interviews, not internal product vocabulary.
- Lead with WHO, then WHAT they're trying to do, then WHAT'S currently broken.

Output as the first section of the Spec doc under heading "Problem".

Define the user (one persona, not a list)

30 min

Specs that try to serve three personas usually serve none. Pick the one user whose problem this feature solves and write the spec for them. Other personas are out of scope and can be addressed in v2.

Tasks

Name the primary user (role, company size, level of technical sophistication)
List the secondary users who'll touch the feature but aren't the focus
Note any users this feature explicitly does NOT serve

Pointers

GuideJobs-to-be-done framework

Gotchas

If you can't name the user without using your product's internal jargon, you don't have a real persona, you have an internal abstraction.
'Power user' and 'casual user' are not personas. They're projections of how you think about your users, not how they think about themselves.

Pick a single success metric (and a guardrail)

1 hr

One number that tells you the feature worked, and one number that tells you it didn't break something else. If the success metric goes up but the guardrail goes down, you didn't ship a win, you shipped a tradeoff. Be honest about that.

Tasks

Pick the success metric (must be measurable in your existing analytics)
Pick the guardrail metric (often retention, latency, or revenue per user)
Write the target ('we expect this metric to move from X to Y in 30 days')
Write the kill criteria ('if this guardrail drops more than Z%, we roll back')

Pointers

GuideOKRs vs KPIs (Lenny Rachitsky)GuideGoodhart's Law in product

Gotchas

'Engagement' is not a metric. Pick a specific behavior that signals the user got value.
If your success metric is the count of clicks on the feature itself, you've measured the feature's existence, not its impact.

Agent prompt for this step

Read the problem statement and propose 3 candidate success metrics + 1 guardrail metric.

Constraints:
- The success metric must be measurable in the user's existing analytics stack (ask if unsure).
- Phrase as "X / Y / over time-window" (e.g. "weekly-active sessions per user / total weekly sessions / 30-day rolling").
- Avoid vanity metrics (signups, page views, total users). Pick a leading indicator of the user's job-to-be-done.
- Guardrail should be the metric most likely to silently regress (retention, NPS, latency, revenue per user).

Output as a numbered list with rationale for each.

Write the scope and non-scope sections

1-2 hr

Scope is what's in v1. Non-scope is what's deliberately out of v1, with a one-line reason. Most spec scope creep happens because non-scope was implicit. Write it down. Engineering will thank you.

Tasks

List 3-7 in-scope behaviors as bullets (not user stories yet, just the contour)
List 3-10 explicit non-scope items with one line each on why
Mark the scope items that are P0 (must ship) vs P1 (nice to have, drop if scope grows)

Gotchas

Non-scope is the most-skipped section. It's also the section that prevents the most fights in week 4 of build.
If you can't name 5 things that are out of scope, your scope is probably too large or too vague.

Write user stories with Given/When/Then acceptance criteria

Half a day to a day

User stories without acceptance criteria are wishes. Acceptance criteria written in Given/When/Then form become test cases for free. If the criteria are vague, the test will be vague, and the bug bash will be a fight.

Tasks

Convert each in-scope behavior into 1-3 user stories ('As a X, I want Y, so that Z')
For each story, write 2-5 Given/When/Then acceptance criteria
Mark edge cases (empty state, error state, offline, very-large input)
Identify any story that needs design before engineering can estimate

Pointers

GuideGiven/When/Then by Martin Fowler

Gotchas

If your acceptance criterion is 'the feature works correctly', it's not a criterion, it's a vibe.
Edge cases discovered during the spec write are 10x cheaper to handle than edge cases discovered in QA.

Agent prompt for this step

For each in-scope behavior, draft 1-3 user stories in the format "As a [user], I want [behavior], so that [outcome]".

For each story, draft 3 Given/When/Then acceptance criteria covering:
1. The happy path
2. The most likely edge case (empty state, max input length, offline, race condition)
3. The error case (what happens if the underlying call fails)

Output as Markdown sections, one per user story, with the criteria as a sub-list.

Reference the design and data model

Half a day

Engineering can't estimate without seeing the screens or the data shape. The spec doesn't have to contain the designs (Figma is for that), but it has to LINK to them. Same for the data model: a sketch of the new tables + columns + foreign keys is enough for the architect to spot dragons.

Tasks

Link the Figma file (specific frame URLs, not just the project)
List the new database tables / columns / API endpoints the feature implies
Flag any data model change that requires a backfill
Identify any design decision that's still open (chip them as open questions)

Pointers

OfficialFigma deep linking to frames

Gotchas

Figma links to the project root will get lost in 2 weeks. Always link to specific frame URLs (right-click frame, copy link).
Data model sketches drawn in the spec doc become canonical. Engineering will refer back. Sketch the foreign keys.

Plan the rollout: flagged, percentage, gradual

1 hr

Most features should ship behind a flag, roll out at 1%, hold for 24 hr, then 10%, 50%, 100%. The spec captures the rollout plan + the kill criteria so engineering doesn't have to make those decisions in production at 2 AM.

Tasks

Decide the rollout shape (instant for low-risk, percentage for medium, gradual cohort for high-risk)
Name the feature flag in the spec ('feature.attribution-v2.enabled')
Write the rollout schedule ('1% for 24 hr, 10% for 48 hr, 50% for 72 hr, 100%')
Write the kill criteria ('roll back if guardrail metric drops more than X%')
Identify the dashboard or alert that will tell you the rollout is healthy

Pointers

GuideFeature-flag rollout patterns

Gotchas

A feature flag with no kill switch is a foot-gun. Always include the rollback path in the spec.
Naming the flag in the spec means engineering doesn't have to invent one. Saves a 20-minute Slack thread.

List risks and open questions, then assign owners

30-60 min

Every spec has open questions. The bad spec hides them. The good spec names them, assigns each to a single owner, and gives a due date. The Open questions table in the workspace makes this trackable.

Tasks

Brainstorm 5-10 risks (technical, market, legal, ops)
For each risk, mark probability (low/med/high) and impact (low/med/high)
Brainstorm every open question that's blocking 'engineering can start Monday'
Assign each open question to a single owner with a due date

Gotchas

Open questions without a single owner stay open forever. 'The team' is not an owner.
If you can't name 5 risks, you haven't thought about it hard enough. Think harder, not less.

Agent prompt for this step

Read the spec draft and brainstorm:
1. 5-10 risks (technical / market / legal / ops) with probability + impact ratings.
2. Every open question that would prevent engineering from starting Monday. Phrase each as a question, not a statement.

Output the risks as a Markdown table (Risk / Probability / Impact / Mitigation). Output the open questions as rows for the Open questions surface, each with a single owner field and a 3-day due date.

Review with engineering, then close every open question

60 min meeting + 1-3 days closing questions

Schedule a 60-minute spec review with the engineering lead and the designer. Walk through the spec section by section. Capture every question that comes up. The spec is not done until the Open questions table is empty.

Tasks

Send the spec link 24 hr before the meeting (no exceptions)
Run the meeting: walk through, capture every question that comes up
After the meeting, file each new question into the Open questions table with an owner
Close each question by editing the spec + moving the row to the Decisions log
Once Open questions is empty, mark the spec ready-for-engineering

Pointers

GuideAsync spec review patterns

Gotchas

If the engineering lead won't read the spec before the meeting, the meeting is the spec write. Plan for that.
Don't let the spec ship to engineering with open questions. The team will silently make different assumptions and you'll discover the conflict in week 3.
A 60-minute spec review with no questions usually means engineering didn't read it. Ask one fake question to test.

Hand the template to your agent

Workspace-wide agent prompt.

Paste this into your agent's permanent system prompt so the agent reads, writes, and maintains the template's surfaces as you work through the steps.

Agent system prompt

You are an agent on the "Write a product spec" playbook workspace.

Your role: maintain the four surfaces (Spec, Open questions, Decisions log, Pointers) while the user drafts a feature PRD.

Cadence:
- When the user pastes scrappy notes into chat, append them as a new section in the Spec doc, structured under the matching heading (Problem, Users, Success metric, Scope, User stories, Design + data, Rollout, Risks, Open questions).
- Every time the user resolves an Open question, move the row to Decisions log with the rationale + date.
- When a user story lacks acceptance criteria, prompt the user with 3 candidate Given/When/Then statements they can edit.

First MCP tool calls:
1. list_surfaces(workspace_slug="write-a-product-spec-for-a-feature")
2. get_doc(workspace_slug="write-a-product-spec-for-a-feature", surface_slug="spec")
3. list_rows(workspace_slug="write-a-product-spec-for-a-feature", surface_slug="open-questions")

Do NOT mark the spec ready-for-engineering while Open questions has unresolved rows.

FAQ

Common questions on this template.

How long should a product spec be?: Long enough to answer every reasonable question, short enough that engineering will actually read it. For most feature-sized work that lands inside a single sprint, 600-1,200 words is right. For larger work spanning multiple sprints, 2,000-4,000. If your spec is over 5,000 words and you're not building a payments rewrite, the feature is too big and should be split.
What's the difference between a PRD and a spec?: Different teams use the words differently. The 'PRD' (product requirements document) traditionally focused on user-facing behavior; the 'spec' focused on engineering details. In modern product orgs the line has blurred and most teams use one document covering both. This playbook produces that combined document.
Should I write the spec or should engineering?: Whoever is closest to the user. Most often that's the PM or founder, with engineering reviewing and adding the technical sections (data model, infrastructure, rollout). The worst pattern is engineering writing the spec without user research. The second-worst is the PM writing the spec without consulting engineering. Co-author when the feature is non-trivial.
Can my AI agents help write the spec?: Yes, especially for structured sections. Agents are particularly good at: drafting the user stories + acceptance criteria from your bullet-point notes, brainstorming risks and edge cases, generating Given/When/Then templates, summarising prior art from the codebase. The judgement calls (problem statement, success metric, non-scope) need a human. The playbook ships agent prompts inline for each section.
How do I know my spec is ready for engineering?: Three tests: (1) the Open questions table is empty, (2) engineering can give you a t-shirt-size estimate after reading it (S/M/L), (3) you can read each user story aloud and write a test for it without inventing facts. If any of those fail, the spec needs another pass.

Open this template as a workspace.

We mint a fresh copy in your org with the steps as table rows, the pointers as a separate table, and the brief as a doc. Bring your agents, start checking off boxes.

Open in Dock