prd-writing git:20260504.d9ce952A

Immutable. This exact content never changes and is served at /api/v1/blob/0d7164d070817b86.

---
name: prd-writing
description: Author Product Requirements Documents (PRDs) from scratch — interview-driven scaffolding, opinionated template, publication to docs/prds/NNNN-*.md. Use when the user says "write a PRD for X" / "let's spec this product" / "I have an idea, help me PRD it", when starting a new feature whose intent isn't already settled, or when /orc:prd is invoked. Distinct from orc:to-prd (which transforms existing conversation into a PRD shape) and orc:rfc-writing (which debates *how* after PRD has settled *what & why*).
---

# PRD Writing

A PRD is the contract between product intent and engineering execution. It captures **what we're building, for whom, and why now** — *before* anyone argues about architecture. A good PRD makes the design conversation that follows it 10× faster because half the questions are pre-answered.

## When to write one

Write a PRD when **all** of these are true:

- The work has a **user-facing outcome** — a behavior, capability, or experience changes for someone outside the team.
- The intent is **non-obvious** — there's a real product question (which audience, which metric, which scope), not just an implementation question.
- The work is **non-trivial** — multi-day effort, or coordination across product/design/engineering.

Don't write a PRD for:

- Pure refactors with no user-visible change → use `orc:rfc-writing` if architectural, or just a plan.
- Tactical bug fixes → just fix it.
- One-day features that have no audience question (e.g. "add `--verbose` flag for engineers") → a plan or issue is enough.
- A decision that's already made and documented elsewhere → `orc:adr-writing` to record it.

## PRD vs RFC vs ADR vs plan

| Document | Primary question it answers | Audience |
|----------|----------------------------|----------|
| **PRD** | "What are we building, for whom, and why?" | PM, design, engineering, leadership |
| **RFC** | "How should we build it? What are the alternatives?" | Engineering (and sometimes wider review) |
| **TRD** | "What's the technical contract — interfaces, data, failure modes?" | Engineering |
| **ADR** | "We decided X; here's why." | Future-you and successors |
| **Plan** | "In what order do we ship the slices?" | Whoever is implementing |

A typical lineage: PRD → (TRD) → (RFC if alternatives exist) → plan → ADRs as decisions lock in.

## Where they live

`docs/prds/NNNN-<kebab-feature-name>.md`, where `NNNN` is a four-digit zero-padded sequence (`0001`, `0002`, …). Sequence is monotonic — never reuse a number, even for archived PRDs.

If `docs/prds/` doesn't exist yet, create it and add a one-line `docs/prds/README.md` pointing to this skill.

## Interview checklist (before drafting)

If the user hasn't already answered these in conversation, ask before drafting. Skip questions whose answers are already obvious from context — don't waste user time interviewing them on things they've already said.

1. **Problem.** What user pain or business need triggered this? Quote a real signal — a support thread, a churn metric, a customer ask, a competitive feature, a regulatory deadline.
2. **Audience.** Who specifically benefits? Single persona, multiple personas, internal team, all users? If "all users," push back — usually it's a subset.
3. **Success metric.** How will we know in 90 days that this worked? Pick one primary metric, optionally one or two secondaries. "It feels better" is not a metric.
4. **In scope.** The smallest version of this that delivers the outcome.
5. **Out of scope.** What we are explicitly NOT building (heads off scope creep in review).
6. **Open questions.** What does the author *not yet know* but needs to before implementation?
7. **Dependencies / risks.** External teams, vendors, data, regulatory blockers, prior work that has to land first.

## Template

Every PRD uses this shape. Delete sections that genuinely have no content; **never leave `TBD` or stub placeholder text.** A section that's empty is a lie about being thought through.

```markdown
# PRD NNNN — <Feature title in noun phrase>

- **Status:** Draft | In Review | Approved | Shipped | Archived
- **Author:** <name>
- **Created:** YYYY-MM-DD
- **Last updated:** YYYY-MM-DD
- **Stakeholders:** <PM, design, eng lead, others>
- **Linked tickets:** <Jira/Linear keys, if any>
- **Linked RFCs/ADRs:** <NNNN refs, if any>

## Problem

What user pain or business need does this address? Quote a real signal — support volume, churn cohort, lost-deal reason, customer ask. 1–3 paragraphs. If the problem isn't real to the reader by the end of this section, the PRD has already failed.

## Audience & jobs-to-be-done

Who specifically benefits, and what job are they trying to get done? Use a persona name if your team has them; otherwise describe the role and context. If multiple audiences, list each with the job they care about.

## Success metrics

How will we know in 90 days this worked?

- **Primary:** <one measurable metric with a target — e.g. "CSV export adoption ≥ 30% of weekly active reporting users by 2026-Q3">
- **Secondary (optional):** <one or two supporting metrics>
- **Counter-metric (optional):** <a metric that should NOT regress — e.g. "report page load p95 ≤ 1.2s">

## User stories / acceptance criteria

The minimum behavior set, framed as user-visible outcomes:

- As a <user>, I can <action>, so that <outcome>.
- As a <user>, I can <action>, so that <outcome>.
- ...

For each, include 1–3 acceptance bullets a tester (or QA agent) could check.

## In scope

Concrete capabilities this PRD commits to delivering. Bulleted, specific.

## Out of scope

Capabilities explicitly excluded — both to bound the work and to head off "but what about…" scope creep in review.

## Risks & open questions

Things that could derail the work or that the author needs answered before implementation:

- **Risk:** <what could go wrong, how likely, how bad>
- **Open question:** <what we don't know yet; preferred answer if any; who owns answering>

## Rollout & measurement

How does this get to users?

- **Rollout strategy:** <flag, percentage rollout, beta cohort, big-bang>
- **Instrumentation:** <events / metrics that need to exist BEFORE launch to measure success>
- **Kill criteria:** <what signal would cause us to roll back / pause>

## Appendix (optional)

- Mockups, prior art, competitor analysis, supporting research.
```

## What to do as the model

1. **Confirm a PRD is warranted** — apply the "all of these are true" test above. If borderline, surface the call to the user (PRD / smaller-issue / nothing).
2. **Run the interview** if input is sparse — go through the seven checklist questions, but skip any already answered in context. Batch into 2–3 `AskUserQuestion` calls; don't drip one at a time.
3. **Find the next sequence number** — `ls docs/prds 2>/dev/null | grep -E '^[0-9]{4}-' | sort | tail -1` and increment. Pad to four digits.
4. **Draft from the template.** Fill every section with real content. **Delete sections that genuinely have no content** (e.g. no counter-metric, no appendix) rather than writing `TBD`.
5. **Show the draft to the user for review** before committing. Use `AskUserQuestion`: "Looks good — commit" / "Edit before commit" / "Save as Draft (status flag flipped)".
6. **Commit** via `orc:git-commit`. Suggested message: `docs(prd): NNNN — <kebab title>`.
7. **Cross-link.** If the PRD relates to existing tickets, RFCs, ADRs — link FROM those to the PRD (the link should be the entry point, not the reverse).

## Tone

Plain prose, written by a product-minded engineer for product-and-engineering readers. No marketing voice ("delight", "seamless", "best-in-class"). No "obviously" or "trivially" — if it were obvious, you wouldn't need a PRD. Cite real numbers when you can: support ticket counts, latency budgets, deadline dates, named stakeholders by role.

## Anti-patterns

- **Status: Draft** that never moves. Either get approval or archive — don't let a PRD rot in Draft.
- **PRDs without success metrics.** "We'll know it's good when we see it" is a sign the author didn't think hard enough.
- **PRDs written after the feature shipped.** The "Why" gets sanitized in hindsight; future-you can't tell what was real motivation vs. retrofitted justification.
- **PRDs that read like specs.** If half the content is API shapes and database tables, you're writing a TRD or RFC — promote it accordingly.
- **PRDs without "Out of scope".** Without explicit exclusions, every reviewer will paste in their pet feature and the work doubles.
- **One-line problem statements.** "Users want CSV export" is not a problem statement; it's a solution. The PRD should articulate *the problem CSV export solves*.

## Relationship to `orc:to-prd`

`orc:to-prd` and `prd-writing` solve different problems and coexist:

- **`prd-writing`** (this skill) — author from scratch, interview-driven, scaffolding, publish to `docs/prds/`. Used by `/orc:prd`.
- **`orc:to-prd`** — synthesize an existing conversation into a PRD shape and ship it to an issue tracker (Linear/Jira). Used when the design conversation has already happened in chat and you just need the artifact.

If the user's input is "we just talked through this; write it up" → reach for `orc:to-prd`. If it's "I have an idea, help me PRD it" → reach for `prd-writing`.