Prd

---
description: "Produce a Product Requirements Document that locks product intent. Problem, users, success metrics. Before any engineering plan, with tiers (one-pager / consumer-feature / b2b-internal), a synthesize path, and a review mode. Use when: 'write a PRD', 'spec out a feature', 'product brief', 'product requirements doc', 'define the requirements', 'what are we actually building', or any user-facing business-driven change needing written alignment; skip for refactors, infra, bug fixes, and engineering-internal work (route to /interview or /planning:plan)."
argument-hint: "[tier] [task description] (e.g., /planning:prd, /planning:prd one-pager add gig calendar, /planning:prd review)"
user-invocable: true
disable-model-invocation: false
shell: bash
metadata:
  workflow-stage: contract
  summary: Lock product intent. Problem, users, success metrics. Before planning
---

## Pre-computed context

Current branch: !`git branch --show-current 2>/dev/null || echo "unknown"`
Recent commits: !`git log --oneline -5 2>/dev/null || echo "no commits"`
Working tree status (empty = clean): !`{ git status --porcelain 2>/dev/null || echo "(git status unavailable)"; } | head -10`

## Variables

Arguments: `$ARGUMENTS`

## Purpose

Most product-feature rework comes from skipping the *what for whom and why* layer and jumping straight to *how*. `/planning:prd` produces the lockable product intent contract: what we are building, for which users, against what measurable success, before any engineering plan, exploration, or research begins.

This is the **product-intent** stage. **Upstream of exploration**, **upstream of `/planning:plan`**, and may run **before or alongside `/planning:interview`** depending on task shape:

- `/planning:prd`. Answers *what should we build, for whom, and why*. Outcome-focused. Required for new user-facing features, business-driven changes, cross-team initiatives
- `/planning:interview`. Answers *what is the engineering contract for this task*. Constraint and acceptance-criteria focused. Required whenever intent is fuzzy or underspecified, regardless of source
- Complementary, not redundant. A product feature usually wants both: `/planning:prd` (product intent) → `/planning:interview` (engineering contract) → exploration → research → `/planning:design` → `/planning:plan`. Engineering-internal work skips `/planning:prd` entirely

The PRD is **never an implementation plan**. Boundaries: problem, users, success. Yes. Architecture, files, tests, code shapes. No. That is `/planning:plan`'s job. If the user pulls toward implementation mid-PRD, anchor back to *what for whom* and let `/planning:plan` pick up after.

**Cost framing**: locking product intent up-front is the cheapest version of the conversation. Every later session that runs against a written PRD costs less than one that infers product goals from a half-formed thought.

## Trigger conditions. When to invoke `/planning:prd`

Invoke `/planning:prd` when ALL of these are true:

- The work has a **user-facing surface**. New feature, new screen, new flow, new public API, new external behaviour
- The change is **business- or product-driven**. Solves a user problem, opens a market, hits a metric. Not engineering-internal cleanup
- **Alignment matters**. Multiple stakeholders, cross-team work, or you want a written reference to point the future agent at

## Skip conditions. When to NOT invoke `/planning:prd`

If ANY of these hold, do NOT write a PRD. Tell the user explicitly: *"This is engineering-internal. No PRD. Recommend `/planning:interview` (if intent is fuzzy) or `/planning:plan` (if it's clear)."*

- **Refactors** (no behaviour change)
- **Infrastructure** (build, CI, hooks, config, dependency bumps, lockfiles)
- **Conventions** (rules files, doc updates, lint rules, analyzers)
- **Bug fixes** (a bug already implies the desired behaviour. Fix the gap, no PRD)
- **Single-team engineering work** with no user-visible surface
- **Tooling**, scripts, internal automation
- **Documentation-only** changes

If ambiguous (could go either way), surface the question once and let the user pick. Never silently write a PRD for an engineering-internal task.

## Action Router

Parse `$ARGUMENTS` to determine the action. Tier choice can be passed as the first argument; if absent, ask for it (surface rules below).

| Argument | Action | Use case |
|----------|--------|----------|
| *(empty)* | **Smart default** | If a prior PRD exists for the topic, offer resume/revise/start-fresh. Otherwise prompt for tier + task. |
| `<task description>` (no tier word) | **Full PRD, prompt for tier** | Run skip-condition check, then ask which template tier (one-pager / consumer-feature / B2B-internal). |
| `one-pager <task>` | **Tier 1. Thin one-pager** | Small feature, single team, fast lock. ~½ page. |
| `consumer <task>` or `consumer-feature <task>` | **Tier 2. Consumer feature** | User-facing app feature with metrics, user stories, risk surface. ~1 page. |
| `b2b <task>` or `b2b-internal <task>` | **Tier 3. B2B / internal** | Stakeholders, compliance, integration, rollout, change-management. ~2 pages. |
| `synthesize <task>` | **Synthesis-only PRD** | Skip Q&A. Produce PRD from existing conversation context. Use when conversation already has rich product context and re-asking would waste the user's time. Still runs skip-condition check (Step 1) and survey (Step 2). |
| `review` | **PRD review** | Critique an existing PRD.md against template + skip-conditions. |

Tier choice rationale lives in [`context/templates.md`](context/templates.md). When tier is unclear from the task description, present the three tiers with one-line descriptions. Via `AskUserQuestion` when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on (the side-by-side rendering helps the user choose without skimming docs), numbered inline prose otherwise.

## The PRD process

### Step 1. Skip-condition check (MANDATORY)

Before any other work, validate the request matches the trigger conditions. If it matches the skip conditions, STOP and tell the user:

> *"This looks engineering-internal (`<reason>`). PRDs add cost without value here. Recommend: `/planning:interview` for fuzzy intent OR `/planning:plan` directly if scope is clear."*

Do not proceed unless the user explicitly overrides ("write the PRD anyway") OR clarifies the user-facing/business framing.

### Step 2. Survey before you write

Spend the first turn grounding yourself, in parallel:

- Read the consuming project's `CLAUDE.md` and `AGENTS.md` for product direction and current modules
- Climb to the nearest domain-vocabulary file (e.g. `UBIQUITOUS-LANGUAGE.md`) if the project keeps one and the topic touches a known module. Walk UP from the relevant directory toward repo root and stop at the first match
- `Glob` and `Grep` for keywords from `$ARGUMENTS` to spot existing surfaces
- `git log --oneline -20` for recent product direction
- List the project's own rules files that govern the area (architecture, modules, conventions)
- Note what the topic's contract slice `<contract_dir>/<topic-slug>/` (default `docs/topics/`) already contains, prior PRD, PLAN, design artifacts, and what its memory slice `<memory_dir>/<topic-slug>/` (default `.work/`) holds (exploration/research artifacts)

If a prior `PRD.md` exists for this topic, ask: **resume** (continue from open questions), **revise** (in-place edits, bump `updated:`), or **start fresh** (append a dated restart note capturing why below the PRD's frontmatter, then rewrite; the commit carrying the rewrite states the pivot rationale. The contract is branch-tracked, so git log is the history).

Survey output is a one-paragraph summary in your reply. Then transition to frontier-rounds Q&A.

### Step 3. Pick the template tier

If not specified in `$ARGUMENTS`, surface the tier choice (card only under the `use_ask_user_question` opt-in; numbered prose otherwise):

| Tier | When |
|------|------|
| **1. One-pager** | Small feature, single team owns it, low ambiguity. ~½ page. Sections collapsed; one-line each. |
| **2. Consumer-feature** | User-facing app feature with metrics, 1-2 user stories, risk surface. ~1 page. Full sections. |
| **3. B2B-internal** | Internal/B2B feature with stakeholders, compliance, integration, rollout, change-management. ~2 pages. Full sections + stakeholders, rollout, dependencies/integrations. |

Tier governs section depth, not section presence. All three tiers cover the same seven required sections (problem, goals, non-goals, users + user stories, success metrics, dependencies/risks, open questions). The difference is verbosity.

Full templates: [`context/templates.md`](context/templates.md). Read on demand. Keep main context light.

### Step 3.5. Synthesis-only path (`synthesize`)

When invoked with `synthesize`, skip Step 4 Q&A entirely. Produce the PRD from existing conversation context. Prior discussion, explored files, research findings, user statements already captured in the session. Still runs Step 1 (skip-condition check) and Step 2 (survey grounding).

Use when conversation already contains rich product context and re-asking would waste time. The user is signaling "I've told you enough. Write it." Respect that signal.

If after the survey (Step 2) a required section has NO answerable content in the conversation, note it as an open question rather than forcing Q&A. The PRD with open questions is still useful. `/planning:interview` or `/planning:plan` picks them up downstream.

### Step 4. Drive frontier-rounds Q&A

**Skipped when `synthesize` action was invoked**. Go directly to Step 5.

Ask in frontier rounds: each round surfaces every open question whose prerequisites are settled as one numbered set (grouped by PRD section), each with a recommendation; a question that depends on another still open waits for the round after its prerequisite resolves. Render a round via `AskUserQuestion` only when the plugin's `use_ask_user_question` user config (`${user_config.use_ask_user_question}`) is on and the round is ≤4 independent questions. Inline prose otherwise.

Question shapes that recur, in priority order:

| Section | Highest-value surfacing question |
|---------|----------------------------------|
| Problem | "Whose problem is this, and what do they currently do instead?" |
| Goals | "If we ignore implementation, what changes for the user when this ships?" |
| Non-goals | "What is explicitly out of scope so we don't drift?" |
| Users | "Who is the primary user. One persona or many? Walk me through their day before and after." |
| User stories | "Pick the one most-important journey: as a `<role>` I want to `<action>` so that `<outcome>`." |
| Success metrics | "How will we know it worked? Name the metric and the threshold. Adoption %, conversion %, time saved, error rate." |
| Dependencies / risks | "What outside this team must exist or change for this to ship? What's the biggest risk?" |
| Open questions | "What is genuinely undecided that `/planning:plan` needs an answer to?" |

Stop asking once every required section has either a resolved answer or an explicit "open question with revisit trigger".

### Step 5. Persist the PRD

Derive `<topic-slug>` from the task description or current branch name (kebab-case, ≤40 chars). The same slug `/planning:interview`, `/planning:design`, and `/planning:plan` will use for this topic. Write to `<contract_dir>/<topic-slug>/PRD.md` (default `docs/topics/`). The topic's contract slice, committed on the task branch as it locks; under `contract_tier: local` it joins the memory slice instead. Roots, tier, and precedence resolve per the topic-docs binding [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md). PRD.md lives alongside `PLAN.md` (the plan skill's output) and the topic's design artifacts.

Frontmatter:

```yaml
---
status: draft         # draft | locked | superseded
tier: one-pager       # one-pager | consumer-feature | b2b-internal
created: <ISO-8601 UTC, e.g. 2026-06-04T14:30:00Z>
updated: <ISO-8601 UTC, e.g. 2026-06-04T14:30:00Z>
---
```

Required sections (every tier. Verbosity varies):

1. **Problem**. What is broken, missed, or unmet for users today
2. **Goals**. Outcome-level, not implementation-level
3. **Non-goals**. Explicit out-of-scope items
4. **Users**. Primary persona(s) + 1-2 user stories in `as a <role>, I want <action>, so that <outcome>` form
5. **Success metrics**. Named metric + threshold + measurement window
6. **Dependencies / risks**. Outside-team dependencies + top 1-3 risks with mitigations
7. **Open questions**. Anything genuinely undecided that `/planning:plan` needs answered

Tier-3 (B2B) adds: **Stakeholders**, **Rollout**, **Compliance / integration**.

**Durability over precision.** PRD content describes interfaces, types, and behavioural contracts. Never file paths or line numbers, which go stale before the PRD does. Do not write as if the current implementation structure will persist; the PRD should still read true after a refactor.

**Non-goals graduation edge.** A non-goal that is a permanent, deliberate rejection, not a deferral, outlives the PRD: graduate it to the consuming repo's rejected-concept ledger at `docs/out-of-scope/<concept>.md`, one file per concept, accreting a "Prior requests" log entry each time the concept resurfaces, so future proposals of the same concept get answered by the ledger instead of relitigated. This is a consumer convention with graceful degrade: create the file lazily on first permanent rejection; when the consumer keeps no ledger, the plain Non-goals list suffices.

Test-seam sketching (where the feature will be tested, and at how few seams) is not a PRD concern. It happens in `/planning:design` as a design thread.

Full template structures: [`context/templates.md`](context/templates.md).

Optionally offer to render the finalized PRD as a self-contained HTML pitch view for non-engineer stakeholders: a static generated view, never an editor with real data bound in. PRD.md stays the tracked record. It lands in the topic-docs **ephemeral tier**, never the contract slice beside `PRD.md`; placement and rules: [`${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md`](${CLAUDE_PLUGIN_ROOT}/reference/topic-docs.md).

### Step 6. Hand off

After writing the PRD, recommend the next step. The recommendation depends on remaining ambiguity:

- **Engineering scope still fuzzy** (constraints, untouchable areas, perf budget unclear) → clear context, then `/planning:interview` (it will read the topic's `PRD.md` as scope)
- **Engineering scope is clear, codebase grounding needed** → `/discovery:explore` if installed, otherwise whatever codebase-exploration capability the environment provides
- **Need external research (libs, APIs, comparables)** → `/discovery:research` if installed, otherwise the strongest research capability available
- **Engineering scope clear and externals understood** → `/planning:plan`

Do NOT auto-clear or auto-invoke. Recommend; let the user pull the trigger.

## PRD review mode (`review`)

When invoked with `review`:

1. Locate the topic's `PRD.md` (use slug derivation above)
2. Evaluate against the seven required sections. Flag any missing or fuzzy
3. Evaluate against skip-conditions. Should this PRD even exist? If engineering-internal, recommend supersession with a `/planning:interview` brief
4. Check goals are *outcomes*, not implementations (the most common failure mode)
5. Check success metrics have a *measurement window* and *threshold*, not vague language
6. Present findings: what's strong, what's missing, what to revise

Complementary to `/planning:devils-advocate`. Review checks structure and convention; stress-test (run later against `/planning:plan`'s plan, not the PRD) checks failure modes.

## What this skill does NOT do

- **Does not plan implementation**. The PRD is *what for whom and why*. Architecture, files, tests, code is `/planning:plan`'s job. If you find yourself writing "we'll add `XHandler` to module Y", stop and move that to the open-questions section as an architecture decision for later
- **Does not run exploration or research**. Step 2's survey is a *fast grounding pass*, not deep work. If product framing requires deep external research (competitive analysis, market data), pause the PRD and recommend the research capability first
- **Does not gate other skills**. Engineering-internal tasks skip `/planning:prd` entirely. Even product features can skip if intent is already locked elsewhere (existing roadmap doc, recent ADR, prior PRD)
- **Does not adversarially attack the user's product idea**. Not the PRD's role. If the proposed feature has obvious product risk, surface it once in the *risks* section and continue. Pushback belongs in product review, not PRD authoring
- **Does not write code, run tests, or modify anything outside the topic's contract and memory slices**. Pure product-intent skill

## Composition with other skills

| When | Skill | How it composes |
|---|---|---|
| Pre-PRD: problem still rough, no candidate approach chosen | `/planning:brainstorm` | Diverges cheapest→most-ambitious candidates; the resonating direction feeds this PRD |
| Pre-task: product feature, fuzzy intent | **`/planning:prd`** (this) | Produces the topic's `PRD.md` |
| Pre-task: any fuzzy task. Including post-PRD constraint discovery | `/planning:interview` | Produces the Brief in `PLAN.md` (reads PRD if present) |
| Need codebase grounding | `/discovery:explore` (if installed) | Reads PRD + PLAN as scope |
| Need external evidence | `/discovery:research` (if installed) | Reads PRD + PLAN as scope |
| Need design exploration (types, contracts, topology) | `/planning:design` | Reads PRD + PLAN; produces design artifacts that `/planning:plan` consumes |
| Plan the implementation | `/planning:plan` | Reads PRD + PLAN + explore + research findings |
| Stress-test the plan | `/planning:devils-advocate` | Adversarial pass on `/planning:plan` output (not the PRD) |

`/planning:prd` is sister to `/planning:plan`: one resolves *what for whom and why*; the other resolves *how*. They share the topic slug, share the contract slice, and feed each other.

## Gotchas

- **Goals as outcomes, never implementations.** "Add a search box" is not a goal; "users can find a song from any of its lyrics in <2 seconds" is. Most common PRD failure: goals that pre-decide the architecture
- **Success metrics need a window.** "Increase engagement" is not a metric; "DAU/MAU rises from X to Y over 30 days post-launch" is. If a metric has no number and no window, it can't validate the feature
- **Don't write a PRD for engineering-internal work.** Skip-condition check is mandatory. PRDs for refactors, hooks, lint rules waste cycles and dilute the convention
- **Tier governs verbosity, not which sections exist.** All three tiers have the same seven required sections. Tier-1 is one line per section; tier-3 is a full paragraph. Don't drop sections to "save time". Drop words
- **The PRD is never an architecture document.** When discussion drifts to implementation, anchor back to *what for whom*. Capture architecture questions in the **open questions** section for `/planning:plan` to resolve
- **Resume vs revise vs start-fresh on prior PRDs.** Never silently overwrite. If scope shifted, append a dated restart note capturing why before rewriting