PRD Writing skill for Codex

A PRD is done when an engineer who was not in the room can estimate it, a designer can start flows from it, and anyone can tell whether the shipped feature succeeded. Every requirement is testable, every goal has a number, and every unknown is written down as an open question with an owner instead of being papered over.

Before writing

1. Find the source material. Ask for (or locate in the repo) the feature request, customer quotes, support tickets, analytics, prior PRDs, and any design files. Check docs/, product/, rfcs/ and AGENTS.md for an existing PRD template and use it instead of this one.
2. Ground it in the code. If the product lives in this repo, read the relevant modules, data models and routes before writing. A PRD that asks for “filter by team” when the schema has no team concept must say so in Constraints.
3. Name the decision-maker. One accountable owner approves the PRD. Write their name (or “TBD - ask user”) in the header.
4. Establish the problem’s evidence. If the user has none, say so explicitly in the doc (“Evidence: anecdotal, 3 sales calls”) rather than inventing data.

If the request is a single small change (one screen, under a week of work), stop and use $feature-specs instead. If the team has not yet decided which problem to solve, use $product-discovery first.

Section rules

Section	Must contain	Common failure
Problem	Who is hurt, how, how often, with evidence	Describing the solution as the problem
Goals	2-4 outcomes, each tied to a metric and target	“Improve onboarding” with no number
Non-goals	Things a reader might assume are in scope but are not	Omitted, so scope creeps in review
Users and scenarios	Named segments and 3-6 concrete scenarios	Personas with hobbies, no tasks
Requirements	Numbered, prioritized (P0/P1/P2), testable	Mixing UI details with business rules
Success metrics	Primary metric, guardrails, measurement source	Metrics nobody can query today
Constraints	Tech, legal, compliance, dependencies, deadlines	Discovered during sprint 3
Open questions	Question, owner, due date	Hidden as “TBD” inside requirements
Rollout	Flagging, cohorts, migration, kill switch	“Ship to everyone” by default

Requirements that engineers can build

• Number them (R1, R2…) so tickets, tests and reviews can reference them.
• Priority: P0 = launch blocker, P1 = expected at launch but can slip a week, P2 = follow-up. More than 40% P0 means priorities are not real; push back.
• Write behaviour, not UI: “R4: A workspace admin can remove a member; the member loses access to all workspace projects within 60 s” beats “Add a red Remove button”.
• State limits explicitly: maximum counts, sizes, rate limits, time zones, locales, permissions, and what happens at each limit.
• Each P0 gets acceptance criteria, either inline or linked ($acceptance-criteria).

Metrics that can be measured

For every goal, check the event or table that will measure it exists. If it does not, add a P0 requirement for the instrumentation and point to $analytics-tracking-plan.

| Metric | Type | Baseline | Target | Source | Window |
|---|---|---|---|---|---|
| Invite acceptance rate | Primary | 31% | 45% | events.invite_accepted / invite_sent | 28 days post-launch |
| Support tickets tagged "permissions" | Guardrail | 120/wk | <= 120/wk | Zendesk tag report | weekly |
| p95 members page load | Guardrail | 900 ms | <= 1000 ms | APM | weekly |

If the baseline is unknown, write unknown - measure in week 0 rather than guessing.

Workflow

- [ ] 1. Collect source material and existing template; read relevant code
- [ ] 2. Draft Problem + Goals + Non-goals only; confirm with user before continuing
- [ ] 3. Write scenarios, then derive numbered requirements from them
- [ ] 4. Attach metrics with baselines and data sources
- [ ] 5. List constraints found in the code and dependencies
- [ ] 6. Collect every unknown into Open questions with owners
- [ ] 7. Run the review checklist below; fix or flag each failure
- [ ] 8. Save as docs/prd/<yyyy-mm>-<slug>.md (or the repo's convention)

Step 2 is a deliberate checkpoint: a wrong problem statement wastes everything after it.

Template

# PRD: <feature name>
Owner: <name> | Status: draft | review | approved | Last updated: <date>
Reviewers: eng <name>, design <name>, data <name>

## Problem
<Who, what pain, how often, evidence with links. 3-6 sentences.>

## Goals
1. <outcome> - measured by <metric> from <baseline> to <target> by <date>

## Non-goals
- <explicitly excluded thing and why>

## Users and scenarios
- S1: <segment> wants to <task> when <situation>; today they <workaround>.

## Requirements
| ID | Priority | Requirement | Acceptance |
|---|---|---|---|
| R1 | P0 | <behaviour with limits> | <link or Given/When/Then> |

## Success metrics
<table: metric, type, baseline, target, source, window>

## Constraints and dependencies
## Open questions
| # | Question | Owner | Due |
## Rollout plan
<flag name, cohorts, migration, kill switch, comms>
## Appendix
<research links, designs, alternatives considered>

Reviewing an existing PRD

Run each check and report pass/fail with a fix:

• Problem names a user segment and cites evidence (or admits there is none)
• Problem contains no solution words (“add”, “build”, “button”)
• Every goal has a metric, baseline (or “unknown”), target and date
• At least two non-goals
• Requirements numbered, prioritized, under 40% P0
• No requirement uses fast, easy, intuitive, simple, etc. without a threshold
• Edge cases covered: empty state, permissions, limits, errors, concurrent edits, deletion
• Each metric has a data source that exists or a requirement to create it
• Open questions have owners
• Rollout says how to turn it off

Gotchas

• Ambiguous words hide disagreement. Replace “users” with the segment, “quickly” with a number, “support X” with the specific operations on X.
• Requirements that depend on another team’s API are constraints with a named contact, not assumptions.
• Writing the whole PRD before confirming the problem produces polished waste. Use the step 2 checkpoint.
• Do not invent customer quotes, baselines or market numbers. Mark gaps as gaps.
• A PRD is not a design doc: database schemas and service boundaries go in the engineering design doc ($design-docs-rfcs), linked from the PRD.
• Deleting or migrating customer data is always called out in Rollout with a reversal plan and an explicit sign-off line.

Verification

Hand the requirements table to a fresh read (or re-read it yourself as an engineer) and try to write one test per P0. Any requirement you cannot turn into a test needs rewriting. Then confirm every goal maps to at least one requirement and every P0 requirement serves at least one goal; orphans on either side are cut or justified.