PRD

A PRD (Product Requirements Document) is a written agreement on what you are building, for whom, and how you will know it worked, before anyone commits to a stack, schema, or sprint of tickets. It is product-first: outcomes, users, scope, and risks. Implementation detail lives in engineering plans, ADRs, or markdown task lists that you produce after the PRD is stable enough.

A PRD does not replace conversation with stakeholders; it captures what you decided so agents and teammates share the same north star.

In this handbook, Product Requirements sits after Your first plan so you have already walked a full Plan mode → markdown plan → checkboxes loop. Use the PRD to formalize intent (problem, goals, non-goals, success) the way you would before the next feature; keep execution steps in the kinds of plan files described in Plans in markdown.

What usually goes in a PRD

Exact templates vary by company, but most PRDs answer:

Not primary PRD content: class diagrams, exact API field names, or “step 3 run migration”, unless a constraint is itself a product requirement (for example “must work offline”).

PRD vs engineering plan

For a full Plan mode workflow, draft a long PRD as markdown, then execute it in phases, see Using Plan mode with PRDs.

Example 1, Client-only snack poll (consumer-style)

Aligned with the snack-poll exercise; scoped small on purpose.

Problem

People in the workshop want a single-page way to vote on a snack and see live tallies without signing in.

Goals

• Three snack options; one vote per browser; counts update immediately after voting.
• Persist choice and counts in localStorage so refresh does not reset the whole poll unfairly.
• Clear UX: user understands they already voted; no ambiguous double-vote.

Non-goals

• No server, no accounts, no admin dashboard, no fraud-resistant voting.

Success

• A new user can vote once, see counts change, refresh, and still see their vote reflected.
• Double-vote attempts are blocked or explained in the UI.

Experience notes

• Mobile-first layout; primary CTA obvious.
• Non-goals must stay visible to the agent so it does not “helpfully” add a backend.

Example 2, Export audit log (B2B internal)

Problem

Support cannot answer “who changed this customer’s plan on Tuesday?” without paging engineering.

Goals

• Read-only UI for org admins: filter by user, entity type, date range.
• Export CSV for the current filter (max 50k rows per export; show truncation warning).
• Retention: 90 days online; older data in cold storage (out of scope for v1 beyond a static message).

Non-goals

• Real-time streaming log; mutating audit entries; public API in v1.

Success

• Median time for support to retrieve a relevant audit trail under 2 minutes in UAT.
• No PII beyond what is already in the app’s user profile (reuse existing redaction rules).

Risks

• Large exports must not tie up app workers, use async job + email link if over 10k rows (open question: reuse existing job system?).

Example 3, “Thin” PRD for a small API change

When the change is narrow, a one-pager is enough:

## Title: Idempotent refund webhook

**Problem:** Partner retries webhooks; we occasionally double-credit refunds.

**Goal:** Processing the same webhook delivery twice must not change financial state after the first success.

**In scope:** Handler for `refund.completed` events only; metrics on duplicate detection.

**Out of scope:** New dashboard; changes to non-refund webhooks.

**Acceptance:**
- Duplicate delivery with identical idempotency key returns 200 and no extra ledger rows.
- Logging includes correlation id; no full card numbers in logs.

**Open questions:** Who owns the idempotency key format, us or the partner?

See also