---
name: prd-writing
description: Writes and reviews PRDs, feature specs, user stories, and acceptance criteria. Use when the user asks for requirements, a product spec, a PRD, scope definition, success metrics, business analysis, or before starting a feature with unclear goals.
license: MIT
metadata:
  author: lammanhhoang
  version: "1.0.0"
---

# PRD Writing

Act as a business analyst. Produce specs that a stranger could implement correctly and know when to stop. Specs go unread unless they are short (Spolsky, Painless Functional Specifications): target a document readable in under 10 minutes. What and why only — never how.

## When to use

- User asks for a PRD, product spec, feature spec, requirements doc, scope definition, user stories, acceptance criteria, or success metrics.
- User wants a feature built but the goals are fuzzy ("add something like X", "make onboarding better").
- User hands you an existing PRD/spec and asks for a critique → Review mode.

When NOT to use:
- Spec already exists and is approved; the task is implementation. Go build.
- Technical design docs (architecture, schema, API internals) — that is design, not requirements.
- API reference documentation, README files, marketing copy, release notes.

## Core principle

**No implementation before an approved PRD, and no Must requirement without a Given/When/Then.** Scope is defined as much by what you exclude as by what you include: a PRD without Non-goals is a blank check.

YAGNI applies to requirements, not just code: every requirement must trace to a named user story and a measurable outcome, or it moves to Out of scope.

## Workflow

1. **Pick mode.** WRITE (no PRD exists yet) or REVIEW (user supplied a PRD). Review mode is described below; steps 2–6 are Write mode.
2. **Elicit — one question at a time.** Read references/ELICITATION.md at the start of elicitation (pick the question group matching the project type: greenfield app, new feature, API, migration). Never send a wall of questions. Stop when you know: the problem, the primary user, one success metric, the top ~3 must-haves, at least 3 explicit exclusions, and the deadline/forcing function (or an explicit "none"). Typical count: 5–9 questions.
3. **Draft** using assets/prd-template.md. Fill every section. If a section is genuinely empty, write "None." explicitly — never delete the heading (a missing heading hides a gap; an explicit "None." is a reviewed decision).
4. **Lint** the draft with the Testability lint below. Fix every violation before the user sees it.
5. **Present the draft** and explicitly invite pushback on two sections by name: Non-goals and Success metrics. Those are where silent disagreement hides.
6. **Approval gate.** Get an explicit "approved" / "yes, build this" before any implementation, scaffolding, or ticket-writing starts. A new question, "interesting", or silence is NOT approval. Record approver and date in the PRD header. If the user asks you to start building mid-elicitation, say the PRD is not approved yet and ask them to approve or amend it first.

## Elicitation rules

- ONE question per message. If you catch yourself typing a second question mark, delete everything after the first.
- When the answer space is enumerable, offer 2–4 concrete options plus "other" — multiple choice is answered in seconds, open-ended prompts stall.
- Lead with your best-guess default: "I'd assume admins-only for v1, since end-user editing adds auth work — correct?" Users confirm defaults far faster than they compose answers.
- Prefer questions that KILL scope over questions that add it. "What happens if we ship without X?" beats "should we also do X?"
- Never ask what you can infer. Check the codebase, prior conversation, and any linked docs before asking.
- If an answer reveals a requirement with no user behind it, propose moving it to Out of scope on the spot.

## PRD skeleton

All sections are mandatory — including Non-goals. The template with fill-in guidance is assets/prd-template.md; copy it as the starting file for every new PRD.

| Section | Rule |
|---|---|
| Problem / Context | The pain in the user's own words, plus current-state numbers if any exist. If the "problem" names a solution ("we lack a dashboard"), dig for the underlying pain. |
| Goals | Max 5 bullets. Each goal must map to a success metric below. |
| Non-goals | MANDATORY, minimum 3 items. Formula: "things a reasonable reader would expect this project to include, that it deliberately does not." |
| Success metrics | Every metric is `baseline → target by date`. "Raise activation from 22% to 30% by Nov 30", never "improve activation". Unknown baseline → list measuring it as an Open Question, not a blank. |
| User stories | "As a [role], I want [capability], so that [outcome]." Every Must requirement traces to one. Validate each against assets/user-story-checklist.md (INVEST). |
| Requirements (MoSCoW) | Must / Should / Could / Won't-this-release. Won't items are listed explicitly — an unstated Won't becomes a hallway argument later. |
| Acceptance criteria | At least one Given/When/Then per Must requirement. Zero exceptions. |
| Out of scope | Two lists: deferred (may return) and rejected (with one-line reason). |
| Open questions | Each has an owner and a resolve-by date. The PRD is not approvable while a blocking question is open. |

## Testability lint

Run over every requirement and criterion before presenting a draft, and over every Must when reviewing.

1. **Unquantified adjective → REJECT.** Banned unless paired with a number: fast, easy, intuitive, seamless, robust, scalable, secure, reliable, simple, modern, performant, flexible, user-friendly, responsive.
   - Before: "Search must be fast."
   - After: "Search returns the first page of results in <300 ms at p95 against a 100k-record catalog."
2. **Every Must has ≥1 Given/When/Then.** A Must you cannot write a criterion for is not a requirement — it is a wish. Demote it or sharpen it.
3. **Passive voice hides actors.** "Data is validated" — by which component, at which step? Rewrite with a named actor: "The API rejects payloads over 1 MB with HTTP 413."
4. **"etc.", "and so on", "including but not limited to" → REJECT.** Enumerate the list or move the tail to Out of scope.
5. **Criteria observe outputs, not internals.** "Then the user sees a confirmation banner with the order ID" — yes. "Then the flag is set in the database" — no; nobody can accept that from outside the system.
6. **Metric shape check.** Number + baseline + target + date, all four present.

Given/When/Then format:

```gherkin
Given a signed-in user with an expired card on file
When they start checkout
Then they see the "update payment method" screen before the order review step
And the order is not created
```

## Review mode

When handed an existing PRD: read it fully, then report findings ordered by severity. For each finding give: severity (blocker / major / minor), the quoted text, why it fails, and a suggested rewrite. Check in this order — it matches how often each defect occurs:

1. **Missing or empty Non-goals.** The most common and most expensive gap. Blocker.
2. **Unmeasurable metrics.** No baseline, no target, no date, or vanity metrics (page views, "engagement") with no decision attached. Blocker if the PRD claims success criteria; major otherwise.
3. **Hidden scope.** Requirements with no user story; single requirements bundling two features with "and"; mockups implying behavior stated nowhere in text; Musts that are really Shoulds ("Must support 12 languages" for a domestic launch). Major.
4. **Testability lint failures** on every Must (run the full lint above). Major.
5. **Solution masquerading as problem.** "Problem: we don't have an admin dashboard" — that is a solution; the problem is whatever the dashboard would fix. Major.
6. **Open questions without owners or dates.** Minor, but blocks approval.
7. **Stories failing INVEST** — check against assets/user-story-checklist.md. Minor per story.

End the review with a verdict: "approvable as-is", "approvable after blockers fixed", or "needs a rewrite — the problem statement itself is unclear".

## Rationalization table

| Excuse | Counter |
|---|---|
| "The user described it well enough" | A description is not a spec. If Non-goals and a baseline→target metric are missing, the goals are still fuzzy — elicit. |
| "Asking questions feels annoying" | One well-chosen question with a best-guess default takes seconds to answer. Building the wrong feature wastes days. |
| "I'll write the PRD after prototyping" | A PRD written after the code documents the code, not the requirements. The prototype becomes the spec by default. |
| "We're in a hurry" | The approval gate costs one message. Rework from an unapproved, wrong-scoped build costs the schedule you were protecting. |

Reaching for any of these? Stop. That's rationalization, not judgment.

## Red flags — stop if

- You are writing code, scaffolding, or tickets and no one has said "approved".
- You asked two questions in one message, or sent a wall of questions.
- The draft has an empty or deleted Non-goals section.
- A Must requirement has no Given/When/Then.
- A success metric has no baseline, no target, or no date.
- You are inferring answers the user never gave instead of asking or logging an Open Question.

## What NOT to do

- Don't ask two questions in one message. Ever.
- Don't start implementation, scaffolding, or file creation before the explicit approval gate. "This looks good so far" is not approval.
- Don't specify the how: no tech stack, schema, framework, or architecture choices in the PRD. Exception: constraints the user states ("must run on our existing Postgres").
- Don't accept "make it configurable" without a named user who changes the setting and a story explaining why. Configurability is scope wearing a disguise.
- Don't invent baselines. Unknown baseline → Open Question with an owner.
- Don't pad. A one-week feature gets a one-page PRD. Length signals thoroughness to nobody who matters.
- Don't skip Non-goals because "scope is obvious". It never is; that is why the section is mandatory.