prd

name	prd
description	Draft a Product Requirements Document (PRD) using a milestone-checkbox format: problem, constraints, non-goals, decisions captured, milestones with checkboxes, verification, out-of-scope, open questions. Use when the user says "PRD this", "let's draft a PRD", "/prd [topic]", "write a PRD for X", "scope X as a PRD", or any framing where the deliverable is a planning doc that will guide implementation. Does NOT implement; PRD-only. The output is always a milestone-chunked, checkbox-driven doc that an engineer can tick off as they build.
allowed-tools	["Read","Write","Edit","Bash","Glob","Grep","AskUserQuestion","WebSearch"]

prd

Produce a PRD in a milestone-checkbox format. The PRD's purpose is to capture decisions and break the work into checkable milestones BEFORE any code is written.

When this triggers

• "PRD this", "let's draft a PRD", "let's scope this as a PRD"
• "/prd "
• "write a PRD for X"
• Any time the user signals they want a planning doc rather than implementation

If unsure whether the user wants a PRD or wants you to start coding, ask once.

What the PRD is NOT

• An implementation. Do not write code while drafting.
• A design doc with paragraphs of architecture prose. Decisions go in the table; mechanics go in the milestone checkboxes.
• A free-text wishlist. Every item under a milestone must be a discrete, checkable thing.
• A novel. Aim for ~250-400 lines for a typical scope; ~800+ only if the work spans many deployable PRs.

House format (use this template)

# <Title> PRD

**Status:** Draft, <YYYY-MM-DD>
**Owner:** <name>
**Surface:** <primary file(s) / endpoints / pages affected>

## Problem

<1-3 short paragraphs. State current state, why it's a problem, and the desired outcome. Not a sales pitch - a brief.>

We want to:
1. <outcome 1>
2. <outcome 2>
...

**Success metric** (optional): <one specific, measurable thing that will be true if this build works. From the 5-Whys at the start of scoping. Skip the line entirely if the user couldn't land on one or waved it off - don't pad with a vague metric just to fill the slot.>

## Constraints

What this build has to live within. Two quick gates (below, in Process) decide how much to capture; skip the whole section if the builder has a free hand and the build touches nothing real.

- **Freedom:** <has to fit in | free hand> (and note "prototype - exploring beyond today's setup" if it's a throwaway to rebuild later)
- **Touches:** <the real data / shared systems / real-world actions (send, post, write, pay) involved, or "nothing real">
- **Build on / must not disturb** (when it has to fit in): <what it must use or integrate with, and what it must NOT change, remove or reverse - read-only, no schema changes, vendor/platform choices, decisions made above the builder>
- **Tools it may add** (when it has to fit in): <new tools/models/connections the builder is allowed to add, from the sanctioned set>
- **Data & safety** (when it touches real data or takes real-world actions): <what data it touches, where it must live, compliance, and any real-world action that must be staged for human approval rather than run automatically>
- **Heads-up note** (when buy-in / sign-off is needed): <who'd want a heads-up before this ships or runs, and a literal paste-ready one-paragraph brief the builder can send them to get the nod - actual sentences, not a summary of what they care about>

For a *prototyping* build, tag these "current state - exploring beyond it" and note that productionising later must revisit them. Leave any line out if it genuinely doesn't apply; don't pad.

## Decisions captured (from scoping conversation)

| Question | Decision |
|---|---|
| <decision-shaped question> | <chosen option, with constraint if any> |
| ... | ... |

## Implementation milestones

Milestones are ordered by dependency. State which milestones unblock which.

### M1 - <name>

<one-line purpose. Note dependencies if any.>

- [ ] <discrete checkable item>
- [ ] <discrete checkable item>
- [ ] ...

### M2 - <name>

<one-line purpose>

- [ ] ...

<...>

### M<N> - Verification

Run before merging:

- [ ] <acceptance check 1>
- [ ] <acceptance check 2>
- [ ] Whatever this project's standard pre-merge check is (build / type-check / tests). If the project has no test suite, manual smoke checks are fine.
- [ ] Manual smoke checks specific to the feature

## Out of scope / future additions

One combined list. Each line is either:
- A deliberate "we're not doing this" (with reason - prevents scope creep), OR
- A deferred "future PRD when X" (with trigger - prevents silently dropped work)

Examples:
- Multi-step branching form - *deliberate; one page only for v1*
- A/B testing the question set - *deferred; separate PRD when v1 has 50 submissions*

## Open questions to resolve during implementation

- <question only the implementer can answer in-flight>
- ...

## Pre-mortem flags

Run after the rest of the doc is drafted. Two dimensions:

**Technical risks (will the build itself fail?):**
- <e.g. "Kit API rate limit hit if we submit during a campaign send - need to verify in M2">

**Strategic risks (will the build achieve the success metric even if it ships?):**
- <e.g. "Form may not change discovery-call time if buyers ignore the routing and book a call anyway">

For each flag, name the milestone or open question that will catch it.

## Research grounding (include only when the PRD rests on external or recency-sensitive facts)

One line per verified claim, each with a source URL and the date checked. Note the tool used (Perplexity sonar-pro / web search). Omit this whole section for purely-internal PRDs (copy, data, refactors with no external dependency).

- <claim, verified one-liner> - source: <url>

Process

1. Confirm the scope. Before asking anything else, confirm in one sentence what you understood the user wants to PRD. If they used a vague handle ("the upsell thing", "the auth refactor"), restate it concretely. If the ask clearly spans 4+ largely-independent deliverables (or would run past ~800 lines), name the scope risk now and ask whether they want one large roadmap PRD or phased single-module PRDs - don't silently accept an over-scoped framing.

2. Probe the underlying goal with a real 5-Whys. Before scoping the build, dig into WHY the user wants it - a genuine 5-Whys, not a single question. "Why do you need this? ... and why does that matter? ... what changes if it works?" - peel a few layers until you reach the real outcome, not the surface ask. If a measurable success metric emerges (e.g. "cut discovery-call qualification time by 50%", "convert 3 more team-tier deals per month"), capture it as the Success metric line under Problem; if it's quantitative, also ask whether the baseline is tracked today and how it'll be measured after launch, and if it isn't, add a baseline-capture item to M1 - a metric with no baseline anchor is unmeasurable. If none lands, that's fine - skip the line and note in the pre-mortem that the strategic-risk dimension will be less precise. Don't interrogate to exhaustion, but don't stop at the first answer either.

3. Read existing context - and if there's little or none, push hard for it. Skim the files the PRD will touch (the page, the API endpoint, the data file) - a couple of Read / grep calls to ground the questions. If the project or folder is empty or near-empty (nothing real to ground on), do NOT proceed on vibes - a PRD grounded in nothing is a PRD of invented assumptions, and the build that follows inherits every wrong guess. Explicitly ask for context and keep nudging until you have real material: "What can you point me at? Existing docs or notes, examples or screenshots of something similar, user interviews or call transcripts, data exports, links, or the current way this is done by hand." Tell them plainly that more context means a sharper, more grounded PRD and a build that gets it right first time. Only proceed once you have something concrete to work from, or they confirm there genuinely is none. This is a hard gate, not a nicety: if your grounding reads turned up nothing concrete, fire one AskUserQuestion for context and do NOT advance to the gates or interview until the user has supplied material or explicitly confirmed there is none - skipping this on a near-empty project is the single most common way this skill produces an invented PRD.

4. Skim ONE existing PRD as a tone reference if the project has prior PRDs - look for *-prd.md files in and read the most recent or most similar in scope. If the project has no prior PRDs, the template above is the reference.

• Technical: will the implementation itself fail? (API rate limits, missing context, environment quirks, edge cases the milestones don't cover, an unverified external assumption from step 5)
• Strategic: even if it ships cleanly, will it achieve the Success metric? (wrong user assumption, missing distribution, depends on a behaviour change that won't happen)

Also run a constraints check: does any milestone assume changing something the Constraints section marks off-limits, adding a tool that isn't sanctioned, or taking a real-world action that should be staged for approval? Each is a flag tied to the milestone that would hit it.

If any pre-mortem flag would change a milestone's shape rather than just warn about it, it was caught too late - treat it as a missed interview question: add a Decisions-captured row and fix the affected milestone checkboxes before handing over, don't leave a prose warning that defers a structural call to the build agent.

Write the flags into the Pre-mortem flags section of the PRD. For each flag, point to the milestone or open question that will catch it. Then present the flags back to the user and ask explicitly: "Want to do a revision pass before handing this to a build agent?" If they say yes, loop back to steps 6-7 with the pre-mortem as input. 12. Update the project's docs index if one exists. Look for docs/index.md (or a similar catalogue file) and add a wiki-link entry under the appropriate section. 13. End-of-turn summary: one or two sentences naming the file path and the milestone count. No more.

Where to save

• Inside a git repo: <repo>/docs/<area>/<topic>-prd.md. Pick the area from the closest existing PRD's neighbours, or sensible top-level categories like growth/, product/, internal/, infra/. If unsure, ask the user once.
• Outside a repo: ~/Documents/prds/<topic>-prd.md (create the directory if needed). Don't park PRDs in /tmp - they're durable artefacts.

Filename convention: kebab-case-prd.md. Lowercase. The -prd.md suffix is load-bearing for greps.

Things to get right

• Success metric is default but skippable. Ask once; if the user has one, capture it. If they don't or wave it off, skip the line and note in pre-mortem that strategic risks will be less precise. Don't pad with a vague metric just to fill the slot, and don't refuse to scope without one.
• Every milestone item is a discrete check. "Update the hero" is not a check; "Hero pill copy: 'Next live cohort: late June 2026'" is.
• Don't emit invented numbers as decisions. Any numeric threshold, weight, or parameter that appears verbatim in a milestone must either come from the user or be tagged (illustrative - confirm in implementation). The silent check guards sections; this guards the values inside them.
• State copy verbatim in the PRD when copy is part of the deliverable. Don't write "update the hero copy"; write the exact line. The PRD is the source of truth so the implementer doesn't re-decide the wording mid-PR.
• Include line numbers when referring to specific spots in existing files (e.g. path/to/file.ts:142). A PRD that says "the CTA block" without coordinates costs an extra grep at implementation time.
• The decisions table is non-negotiable. Every clarification you asked must appear there. If a decision was implied (not asked), still capture it in the table so the implementer can challenge it later.
• Constraints are load-bearing for non-owners. When the builder doesn't own the surrounding systems, the Constraints section is what stops the build agent proposing to rip out a sanctioned tool, connect an unapproved one, or auto-run a real-world action. Two gates (freedom + reality) decide how much to ask - for a free hand over something that touches nothing real, ask nothing. Keep the tone "I'm arming you", never "I'm auditing you": the heads-up note is a brief the agent drafts for the builder to win sign-off, not a gate. The reality gate (Gate B) is the one that catches the dangerous case - a free hand or a prototype can still be piping regulated data through an LLM or auto-emailing real people.
• Milestones over PRs. Default to milestones (M1, M2, ...). Only switch to PR-numbered sections (PR 1, PR 2a, ...) when the work clearly spans multiple deployable shipments and the user has confirmed that intent.
• The verification milestone is mandatory. Even small PRDs end with an M that is the merge gate. Pulls together whatever this project's standard pre-merge check is plus feature-specific manual smoke.
• Out of scope / future additions is one combined list. Each line is either deliberate ("we're not doing this") or deferred ("future PRD when X"). Label which. Never split into two sections - participants confuse them and end up with overlap.

Things to avoid

• Do NOT write the implementation while drafting. Resist any urge to also Edit the page during the PRD step. The user will say "ok let's build" as a separate signal.
• Do NOT pad the doc with rationale for every decision; the table captures it. Rationale belongs in PR descriptions and decision logs.
• Do NOT merge milestones to look smaller. M1 + M2 collapsed into "M1: do everything" defeats the point - the dependency graph and per-PR sizing are the value.
• Do NOT add testing checkboxes inside every feature milestone and a verification milestone - duplicates the work. Feature milestones reference unit tests they need; the verification milestone runs the full project suite once.

Reference

The template in "House format" above is the structural reference. If this project has prior PRDs in docs/, skim one as a tone reference (step 4 of Process).