---
title: "Write a product spec for a feature that ships"
excerpt: "9-step playbook for writing a feature spec that engineering can start on Monday with zero open questions and no surprise scope."
category: "Template"
---

# Write a product spec for a feature that ships

    A 9-step playbook. Open in Dock and you'll get four surfaces seeded:

    - **Spec** (doc) - the canonical PRD with all 9 sections
    - **Open questions** (table) - one row per unresolved question, with owner and due date
    - **Decisions log** (table) - one row per decision made, with date and rationale
    - **Pointers** (table) - linked design files, prior art, customer interviews

    Read `Spec` top-to-bottom. Open questions get filed as you go. Don't move to engineering kickoff until the table is empty.

## 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.

**Estimated time:** 1-3 days of focused writing, plus 2-5 days of review  
**Difficulty:** intermediate  
**For:** PMs, founders, and tech leads writing feature PRDs.

## What you'll need

Pre-register or install before you start.

- **[Linear](https://linear.app/)** _(Free for up to 10 users, $8/user/mo Standard)_ — File the spec as an issue + link the engineering subtasks underneath.
- **[Figma](https://www.figma.com/)** _(Free tier, $15/editor/mo Professional)_ — Wireframes and design references the spec links to.
- **[Loom](https://www.loom.com/)** _(Free for 25 videos, $15/creator/mo Business)_ — Record a 5-minute walk-through of the spec for async review.
- **[Notion or Dock](https://trydock.ai/)** _(Free tier, $19/mo Pro on Dock)_ — Host the spec doc itself, with comments and a versioned history.

---

# The template · 9 steps

## Step 1: Write the problem statement (one paragraph, no solution)

_Estimated time: 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

- **[Guide]** [Marty Cagan: product discovery](https://www.svpg.com/four-big-risks/)
- **[Guide]** [Teresa Torres on opportunity solution trees](https://www.producttalk.org/2016/08/opportunity-solution-tree/)

> [!CAUTION]
> **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

```text
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".
```

## Step 2: Define the user (one persona, not a list)

_Estimated time: 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

- **[Guide]** [Jobs-to-be-done framework](https://hbr.org/2016/09/know-your-customers-jobs-to-be-done)

> [!CAUTION]
> **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.

## Step 3: Pick a single success metric (and a guardrail)

_Estimated time: 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

- **[Guide]** [OKRs vs KPIs (Lenny Rachitsky)](https://www.lennysnewsletter.com/p/the-ultimate-guide-to-okrs)
- **[Guide]** [Goodhart's Law in product](https://en.wikipedia.org/wiki/Goodhart%27s_law)

> [!CAUTION]
> **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

```text
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.
```

## Step 4: Write the scope and non-scope sections

_Estimated time: 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)

> [!CAUTION]
> **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.

## Step 5: Write user stories with Given/When/Then acceptance criteria

_Estimated time: 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

- **[Guide]** [Given/When/Then by Martin Fowler](https://martinfowler.com/bliki/GivenWhenThen.html)

> [!CAUTION]
> **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

```text
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.
```

## Step 6: Reference the design and data model

_Estimated time: 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

- **[Official]** [Figma deep linking to frames](https://help.figma.com/hc/en-us/articles/360057440213-Get-and-share-Figma-design-and-prototype-links)

> [!CAUTION]
> **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.

## Step 7: Plan the rollout: flagged, percentage, gradual

_Estimated time: 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

- **[Guide]** [Feature-flag rollout patterns](https://martinfowler.com/articles/feature-toggles.html)

> [!CAUTION]
> **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.

## Step 8: List risks and open questions, then assign owners

_Estimated time: 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

> [!CAUTION]
> **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

```text
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.
```

## Step 9: Review with engineering, then close every open question

_Estimated time: 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

- **[Guide]** [Async spec review patterns](https://www.shortform.com/blog/loom-async-meetings/)

> [!CAUTION]
> **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

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

```text
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

### 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.