writing-prds

What this skill does

# Writing PRDs

A PRD is the input contract for the planning phase. A good PRD lets a planning
agent produce a usable plan in one shot instead of burning turns asking "what did
you mean by X?". A bad PRD causes planner thrash, review rejection, and
verification failures downstream.

This skill is platform-agnostic. It assumes a plan → review → verify → ship flow
where a PRD is written first, a planner decomposes it into steps, and a verifier
checks the result against the PRD's acceptance criteria. Adapt the storage and
field mechanics below to whatever tracker you use.

## Storage Location

**Prefer making the tracker issue body the PRD.** One document per work item, one
location: the body of an issue in the project's tracker (a GitHub issue is the
recommended default). Avoid scattering PRDs across local sidecar files that drift
out of sync the moment work starts.

- **Create** a PRD by creating an issue whose body is clean PRD markdown.
- **Edit** a PRD by editing that issue's body.
- **Version history** is the tracker's edit history — no manual `updated` field.
- **The planner reads the issue body verbatim.** What you write in the body is
  exactly what the planning agent sees, so it must stand alone.

If there is no connected tracker, decide on the single canonical location for the
PRD before writing — do not draft into a throwaway scratch file that nobody will
find again.

## Native Tracker Metadata

Do not put YAML frontmatter at the top of issue bodies. Trackers render
issue-body frontmatter as visible noise and already have native fields for this
metadata.

Use native tracker / project-board fields instead:

- **Issue type:** `Feature`, `Bug`, or `Task`.
- **Status:** `Todo`, `In Progress`, `Done`, or `On hold`.
- **Priority:** `P0`, `P1`, `P2`, or `P3`.
- **Complexity:** `Low`, `Medium`, or `High`.
- **Blast radius:** `Contained`, `Cross-package`, `Cross-app`, or `Infra`.

Rules:

- The PRD body starts with `# PRD: <name>` and contains only human-readable PRD content.
- Put card/list summaries in the issue title, project fields, or a short Executive Summary, not in hidden metadata.
- If you cannot estimate complexity, set the field to `Medium` and explain why in Risks & Open Questions.
- `Draft` is workflow state, not body text. Keep draft PRDs off the runnable board path through status fields, not by editing the body.

## Issue Title Style

The issue title is what the board shows most of the time. Keep it short.

- Prefer **4-7 words** when possible.
- Prefer an **imperative verb + object** shape: `Add pipeline checkpoints`, `Track CI blockers on issues`, `Expose model selectors in settings`.
- Put the detail in the Executive Summary and body, not in the title.
- Avoid titles chained together with `and` / `while` / `during` unless the feature is truly one inseparable unit.
- Avoid titles that restate the full implementation loop. The title names the work item; the PRD explains it.
- Keep the `# PRD:` name aligned with the final issue title's slugified form. If you shorten the title, shorten the PRD heading too.

Bad:

- `Open draft PR during execution and ingest PR feedback into stabilization loop`
- `Treat CI failures as blocker state on GitHub issue tasks`

Better:

- `Add draft PR feedback loop`
- `Track CI blockers on issues`

## Required Sections

Every PRD must have these sections, in this order. Missing sections fail quality gate.

```markdown
# PRD: <name>

## Executive Summary
<2–4 sentences. What is this feature, why now, who wins.>

## Problem Statement
<The concrete pain. Reference real incidents, real users, real metrics where possible.
Avoid "users might want..." — if you can't name the user, you don't have a problem yet.>

## Goals
- <measurable, verifiable goal>
- <measurable, verifiable goal>

## Non-Goals
- <thing this explicitly does NOT do — the more you list, the less scope creep downstream>

## User Stories
- As a <role>, I want <capability> so that <outcome>.
- Each story ends with "**Acceptance:**" followed by 1–3 concrete checks.

## Functional Requirements
<Numbered list. Each item must be verifiable by reading code or running it.
NO implementation details — "the system must do X", not "use Zustand to do X".>

## Non-Functional Requirements
<Performance, accessibility, error-handling, offline, observability.
Only list the ones that actually matter for this feature.>

## Success Criteria
<The bar the verification phase will check against.
Every bullet here becomes an acceptance criterion the verifier asserts on.
Write them like test assertions.>

## Out of Scope
<Be ruthless. Future-proofs the review phase against scope creep.>

## Dependencies
<Other PRDs, packages, external APIs, feature flags. Reference by path or URL.>

## Verification Plan
<How the verifier will know this shipped correctly.
`tests`: list the test files/suites that must exist and pass.
`manual`: list the manual QA steps a human will run post-merge.
`both`: both sections. The clearer this section, the fewer verification retries you burn.>

## Risks & Open Questions
<Unknowns, edge cases, things that could kill the plan mid-execution.
Open questions get tracked here until answered, then deleted.>
```

## Mapping PRD Sections to the Plan

A PRD is read by the planning agent. Every section has a downstream consumer:

| PRD section | Feeds | Consumer |
|---|---|---|
| Executive Summary | Plan objective | Plan display, PR title, board card |
| Goals + Functional Requirements | Plan steps | Planner decomposition |
| Success Criteria | Acceptance criteria | Verification phase |
| Out of Scope | Plan out-of-scope list | Review phase (rejects scope creep) |
| Complexity field | Estimated complexity | Review rubric, retry budget |
| Verification Plan | Verification prompt input | Verification phase |
| Non-Goals + Out of Scope | Review gate | Reviewer rejects patches that violate these |

**Do not write sections that describe files to change, function names, or implementation choices.** Those belong in the plan, not the PRD. If you can't resist writing pseudo-code, put it under "Risks & Open Questions" as "I suspect we'll need to touch X" — not as a requirement.

## Quality Gates

Before marking a PRD ready for a planner to consume, every one of these must be true:

- [ ] No placeholder text (`TODO`, `TBD`, `<fill this in>`) remains in any section.
- [ ] `Goals` has at least one measurable bullet.
- [ ] `Success Criteria` has at least one bullet, and every bullet is **verifiable without judgement** — it either passes or fails. "Feels fast" is not verifiable. "p95 latency < 300ms on the issues query" is.
- [ ] `Out of Scope` has at least one bullet. Empty `Out of Scope` is a tell that the author didn't scope the feature.
- [ ] `User Stories` has at least one story with explicit Acceptance bullets.
- [ ] Every external dependency in `Dependencies` is named (package, PRD path, or URL), not described vaguely.
- [ ] `Verification Plan` names either test file paths, suite names, or concrete manual steps — not "write some tests".

If any gate fails, keep it in draft/on-hold workflow state and do not mark it ready to plan.

## Workflow

### When the user says "write a PRD for X"

1. **Confirm where the PRD will live.** If using a tracker, confirm the target repo/project. If nothing is connected, agree on the single canonical location first — there must be exactly one.

2. **Do not start writing immediately.** Run a short elicitation pass first — you need answers before section-filling is meaningful:
   - What problem does this solve, and for whom specifically?
   - What does success look like — how would we measure it?
   - What is explicitly out of scope?
   - What's the complexity gut feel (low/medium/high) and why?
   - Any hard constraints — deadlines, other projects in flight, package boundaries?

3. **Check for an existing issue.** If using GitHub, run `gh issue list --search "<keywords>" --state all` in the target repo. If a matching issue already exists,