---
name: prd
description: Use when you're about to build something — an app, a feature, a tool, an automation — and you want to turn a fuzzy idea into a clear brief BEFORE anyone (or any AI) starts building. Especially when you'll hand it to an AI coding agent (Claude Code, Cursor) to build for you, when you've been burned by the AI building the wrong thing / over-engineering / quietly expanding scope, or when "I'll just explain it as I go" keeps producing a mess. Produces a Product Requirements Document (PRD) — a spec clear enough that a builder who has never spoken to you could build the right thing without guessing.
---

# PRD — Write the Brief Before You Build

## Overview

A skill for one job: **turn a fuzzy idea into a brief clear enough to build from — first time, without a back-and-forth.** Modern twist: the builder is increasingly an AI, and an AI builds *exactly* what you wrote, not what you meant. So the bar is higher and simpler: **"could an AI build this without asking me a single question?"** If the answer is no, the PRD isn't done.

**The core move:** *problem first, "done" defined, scope fenced — then detail.* Most build failures are decided before any code: a fuzzy problem, an undefined "done", and an unfenced scope. Nail those three and the rest is detail.

**Core principle:** *An hour on the brief saves a day of building the wrong thing.* Vague specs don't fail at the spec stage — they fail expensively, later, as rework and "that's not what I wanted." The PRD is where you make the cheap mistakes.

**Announce at start:** "I'm going to write this as a PRD — a build brief. I'll nail the problem, define what 'done' looks like, fence the scope, then make it concrete enough to build from. I'll ask you the questions a builder would otherwise have to guess at."

## When to use

- About to build an app, feature, tool, automation, or script — for yourself or to hand off.
- **Handing the build to an AI agent** (Claude Code, Cursor, Cowork) — this is where a sharp spec pays the most.
- You've been burned: the AI built the wrong thing, over-engineered, or kept "improving" things you didn't ask for.
- A fuzzy idea you can feel is real but can't yet hand to anyone.

## When to skip

- A tiny, obvious, reversible change — just do it.
- You're still exploring whether the idea is worth doing at all (use `deep-thinking` or `red-team` first; PRD comes *after* you've decided to build).
- You don't yet understand the problem — go learn it. A PRD written on a guessed problem is confident rework.

## The method

Work top to bottom. Each section earns its place; if a section is empty, say why rather than padding it.

### 1. The problem — one paragraph, first
Before any solution: **who** has the problem, **what** the pain is, **why** it matters, and any **evidence** it's real. One tight paragraph. If you can't state the problem clearly without describing the solution, you don't understand it yet — stop and dig. (Lenny Rachitsky: nailing the problem statement is the single highest-leverage step. Marty Cagan: discovery before documentation.)

### 2. Define "done" — measurable success
What does *working* look like? State the outcome concretely enough to test. Replace "fast / intuitive / better" with something checkable ("loads in under 2 seconds", "a new user completes signup without help", "the report matches the spreadsheet to the penny"). Add a **guardrail** where it matters ("…without breaking the existing X"). For an AI build, these become your **acceptance criteria** (step 5).

> **Power move (optional, from Amazon):** write the one-paragraph *announcement* of the finished thing first — "Today we launched X, which lets [user] finally [outcome]." If you can't write an exciting, specific announcement, the idea isn't sharp yet.

### 3. Who it's for + the core stories
Name the user(s). Then the handful of **core stories** in plain form: *"As a [user], I want to [do thing], so that [outcome]."* Stories carry **intent** — they stop a builder implementing the letter and missing the point.

### 4. Scope — Must-have vs Won't-do (the most important section)
- **Must-have:** the smallest set that solves the problem. Resist "while we're in there."
- **Won't-do / out of scope:** list it *as deliberately as the must-haves.* This is the single biggest lever against scope creep and against an AI over-building. Name the tempting-but-excluded things explicitly: *"Not doing accounts/login. Not doing payments. Not doing mobile yet."*
- **When the builder is an AI, sharpen "won't-do" into three tiers.** This is the highest-leverage few lines in the whole brief, because an AI will do anything you don't fence off:
  - **Always do** without asking — e.g. "match the existing code style", "keep every change inside /new".
  - **Ask first** before doing — e.g. "ask before adding any dependency, or any new file".
  - **Never do** — e.g. "never add a database", "never touch files outside /new", "never change things I didn't ask you to change".

### 5. Make it buildable — concrete enough that nobody has to guess
This is what separates a wish from a spec, and what an AI needs most:
- **Acceptance criteria, testable:** for each must-have, *Given [situation], when [action], then [result].* "Done" = these are true.
- **Real examples beat descriptions:** one concrete input → expected output is worth three paragraphs. Show the actual thing (a sample screen, a sample row, a sample message).
- **Edge cases, named:** what happens when it's empty? too big? wrong? offline? AI agents default to the happy path unless you spell out the edges.
- **Constraints & stack:** any fixed choices — language, tools, where it runs, must-use or must-avoid. Without these, an AI picks for you, often wrong.

### 6. Constraints, dependencies, open questions
What limits this (time, budget, platform, compliance)? What does it depend on (an API, a login, another system)? What's still **unknown** — list the open questions honestly rather than papering over them.

### 7. Phase it (if it's big)
A great PRD is small. If the thing is large, **split it into phases** and spec the *smallest valuable slice* first — ship that, learn, then the next. (Practical AI reason: coding agents degrade past ~150–200 instructions; a 300-requirement spec builds worse than three 50-requirement phases delivered in turn. Human reason: you learn more from one shipped slice than ten planned ones.)

## A tiny worked example

The format in miniature. This is what "concrete enough to build from" actually looks like:

> **Problem:** I have 2,000 photos with camera-default names (IMG_4821.jpg), so I can't find anything by date, and renaming them by hand is hours of work I keep postponing.
> **Done:** I run one command on a folder and every photo is renamed to `YYYY-MM-DD-NN.jpg` using its capture date, with nothing outside that folder touched.
> **Must-have:** rename by EXIF capture date; cope with a folder of mixed file types. **Won't-do:** no GUI, no cloud upload, no video files yet.
> **Acceptance criterion:** *Given* a folder containing `IMG_4821.jpg` taken on 2024-03-05, *when* I run the tool, *then* that file becomes `2024-03-05-01.jpg` and no other folder is modified.
> **Edge cases named:** two photos in the same second get `-01` / `-02`; a photo with no capture date is left untouched and listed in a short report.

Five lines, and a builder who has never spoken to you could start. That is the bar.

## The loop — iterate to a bar, then stop

Draft the PRD, then test it against the bar and tighten — don't hand over draft one.

- **The bar (all must be true):**
  1. The problem is stated in one clear paragraph, solution-free.
  2. "Done" is **measurable** — you could check it.
  3. Scope has an explicit **Won't-do** list.
  4. Every must-have has a **testable** acceptance criterion.
  5. **The "could an AI build this without asking a question?" test passes** — read it as a builder; every place you'd have to guess is a gap to fill. The cheapest way to actually run this test: paste the draft into a *fresh* chat and ask it to build the thing. Every question it comes back with is a gap you just found for free.
  6. It's short enough to actually be read (a few pages, not twenty).
- **Each round:** read it as the builder, list every ambiguity or guess, fix those specifically. Repeat until the bar is met or the round cap (default **3**).
- Stop at the bar — a PRD can be over-specified too (don't dictate *how* to build what a competent builder/AI should decide). Define the *what* and the *done*; leave room on the *how* unless the how is a real constraint.

## Output shape

> **The PRD** — in this order, scannable, a few pages max:
> 1. **Problem** (one paragraph) + **Success / "done"** (measurable) — the two things up top.
> 2. **Users + core stories.**
> 3. **Scope: Must-have / Won't-do.**
> 4. **Requirements** — each with a testable acceptance criterion + a concrete example.
> 5. **Constraints, dependencies, open questions.**
> 6. **Phases** (if split).
>
> End with the one-line **hand-off**: *"Build Phase 1 only. Done = [the measurable bar]. Don't build anything in the Won't-do list. Ask before [the Ask-first items]."*

## Honesty rules (non-negotiable)

- **Problem before solution. Always.** If the draft opens with features/screens, it skipped the problem. Go back.
- **Measurable or it doesn't count.** "Better / faster / nicer" is not a success criterion. If you can't check it, you can't claim it.
- **Won't-do is as important as Must-have.** A PRD with no out-of-scope section is an invitation to scope creep — and, for an AI, to over-build.
- **If it's not testable, "done" is undefined.** A requirement an AI can't verify is a requirement it will hallucinate the boundaries of.
- **Short or unread.** A PRD nobody reads failed, however thorough. Cut, link, phase.

## Common mistakes / red flags — STOP

- **Feature-list dump.** Starts with "it should let you…" and never says what problem it solves. Lead with the problem.
- **No success metric.** "Improve the experience" — unbuildable, uncheckable. Define a concrete "done".
- **Vague language.** "Intuitive", "fast", "robust" — each reader (and each AI) fills these in differently, and builds something different. Make them concrete and testable.
- **No Won't-do.** The scope has no fence → the build sprawls. Add the explicit out-of-scope list.
- **Solutioning too early.** Wireframes and tech choices before the problem is validated. Problem and "done" first; *how* later.
- **The everything-spec.** 20 pages, 300 requirements, one giant phase. Split it; spec the smallest valuable slice first.
- **(AI-specific) No acceptance criteria.** Handing an AI "add error handling" with no testable definition → it guesses the scope and you get the wrong thing. Spell out Given/When/Then.