prd_writing v1.0.0

name: "prd_writing" description: "Write a product requirements document before building: frame the problem, write user stories that survive contact with code, set testable acceptance criteria, and draw hard scope lines. Triggers on 'write a PRD', 'spec this feature', 'scope this build', or anytime a feature needs a written brief before engineering starts."

PRD Writing

Purpose

Produce a product requirements document that actually prevents rework: one that an engineer can build from without pinging you, and that a stakeholder can sign without surprises.

Workflow

1. Problem first, solution never. Write the problem statement before any requirement. Format: who is hurt, what it costs them, with a number or observation, no proposed fix. A problem statement that names a solution ("users need a dashboard") is a failed first step; rewrite it until the problem stands alone ("users spend 30+ minutes a day assembling metrics from five tools, so reports ship late and contradict each other").
2. Name the persona and the evidence. One PRD covers one persona and one job to be done. State the evidence behind the problem: interviews, support tickets, usage data. If you have none, say so plainly and mark the problem as an assumption to validate.
3. Run the four-risk pass. Before writing requirements, answer: is it valuable (will users choose it), usable (can they figure it out), feasible (can we build it), viable (does the business support it). Anything you cannot answer becomes an open question in the PRD, not a buried guess.
4. Write requirements as behaviors, not tasks. Each requirement describes observable behavior of the system, linked back to the problem it solves. No orphan requirements: if a requirement does not trace to a stated problem, cut it or add the problem it solves.
5. User stories that survive contact with code. Story format: As a [persona], I want [goal], so that [outcome]. Then add the three things most stories skip: the edge cases (empty state, error state, the boundary conditions), the constraints (performance, security, platform), and the non-happening (what the story explicitly does not change). See references/worked-prd-example.md for a full worked example.
6. Acceptance criteria you can test. Every criterion is SMART: specific, measurable, achievable, relevant, time-bound. "Page loads fast" fails; "page loads in under 2 seconds on the P75 of measured sessions" passes. If a criterion cannot be verified by a person running the build, rewrite it until it can.
7. Draw scope with non-goals. Write the non-goals list before you write the timeline. Non-goals are concrete ("no offline mode", "no admin bulk import in v1"), not vibes. Anything deferred gets a named future, not a vague "phase 2".
8. Review loop, in order. Engineering feasibility pass first (they find the lie in the spec), design second (they find the friction), stakeholders last for sign-off. Record decisions and sign-off in the PRD itself. Then run the anti-bloat check in references/anti-bloat-checklist.md and kill what it flags.

Output Contract

A finished PRD contains:

• Title, owner, date, status (draft / in review / signed)
• Problem statement with persona and evidence (or marked assumptions)
• Success metrics with baselines and targets
• Requirements, each traced to a problem, with user stories + edge cases + constraints
• Acceptance criteria that are testable
• Non-goals and explicit scope boundaries
• Open questions with owners
• Review sign-off table
• Freshness: a "re-check by" date. A PRD older than its re-check date is stale and must be re-read before building.

Operating Rules

1. Never invent numbers, dates, quotes, or research findings. Unverifiable evidence gets cut or framed as an assumption.
2. Write the introduction last, after the requirements are stable.
3. One PRD, one persona, one job. If you are writing for three personas, write three PRDs or one PRD with clearly separated tracks.
4. Do not prescribe implementation ("use Redis") unless it is a genuine constraint. Say what the system must do, not how to build it.
5. Keep it short enough that the sign-off table gets filled. A PRD nobody finishes reading is a failed PRD.
6. Template lives in assets/prd-template.md. Copy it to start, do not fill every section out of duty: delete sections that carry no content instead of padding them.