prd

Philosophy: The best PRDs emerge from dialogue, not monologue. The agent drafts, the user validates, and together they surface edge cases, priorities, and assumptions that neither would find alone. A PRD separates product decisions (fixed) from implementation decisions (open for engineering). Every requirement traces back to a user pain and a business goal.

Target duration: BRIEF ~30 minutes, STANDARD ~1-2 hours, COMPREHENSIVE ~2-4 hours. Target length: BRIEF ~1 page, STANDARD ~5-10 pages, COMPREHENSIVE ~10-20 pages.

Why This Matters

A PRD that nobody reads is worse than no PRD — it creates false confidence. This skill produces PRDs that are:

• Co-authored — the user validates problem, personas, and priorities at each stage
• Testable — every acceptance criterion maps to a verifiable test
• Bounded — explicit assumptions, constraints, and non-goals prevent scope creep
• Traceable — stable FR IDs chain through design → plan → beads → tests → code

---

Trigger Conditions

Run this skill when:

• User says "write requirements", "create PRD", "define user stories"
• After brainstorm approval for business features
• After discovery completion for complex features
• Starting a feature that needs formal requirements documentation

Stage Gates — AskUserQuestion

At every PAUSE point in this skill, call the AskUserQuestion tool to present structured options to the user. Do not present options as plain markdown text — use the tool. The YAML blocks at each PAUSE point show the exact parameters to pass.

For pattern details and examples: ../_shared/references/stage-gates.md

Fallback: Only if AskUserQuestion is not available as a tool (check your tool list), fall back to presenting options as markdown text and waiting for freeform response.

Adaptive Pause Density

Track consecutive approvals across all PAUSE points (not just within a single pause). After the user approves 3 or more consecutive gates without any revision, offer to consolidate:

AskUserQuestion:
  question: "You've approved everything so far without changes. Would you like to review remaining phases together or keep individual gates?"
  header: "Review Pacing"
  multiSelect: false
  options:
    - label: "Keep individual gates"
      description: "Continue with focused review at each pause point."
    - label: "Consolidate remaining"
      description: "Present remaining phases together for a single review."

If the user chooses "Consolidate remaining", combine the remaining PAUSE points into a single comprehensive review at the end (before Phase 10 self-review). If the user revises anything at a later gate, reset to individual gates for subsequent pauses.

---

Mode Selection

Determine mode from brainstorm scope classification or ask user:

| Mode | When | What You Get | |------|------|-------------| | BRIEF | Simple feature, 1-2 sprints, BRIEF scope | One-page: Problem, Goals, 3-5 stories with acceptance criteria | | STANDARD | Typical feature, STANDARD scope | Full PRD: all sections, 8-15 stories, personas, NFRs, priorities | | COMPREHENSIVE | Complex feature, COMPREHENSIVE scope | Full PRD + Cockburn use cases + security/compliance criteria |

If brainstorm exists, use its scope classification. Otherwise ask: "How complex is this feature? [brief / standard / comprehensive]"

Policy & Standards PRDs

Not every PRD maps to a single bounded module with its own aggregate root, personas, and CRUD operations. Some PRDs define shared policies, standards, or cross-cutting concerns that multiple modules consume (e.g., error handling contracts, data lifecycle rules, rate limiting policies).

These PRDs still follow the same structural conventions, but some sections may be lighter:

• Personas: May reference project-wide personas rather than defining new ones. Still use the ### P{n}: format, but a 1-line "See [project personas doc]" reference is acceptable if personas are defined centrally.
• Use Cases: May have fewer use cases or none — policy PRDs define rules, not user flows. If there are no use cases, state "N/A — this PRD defines standards consumed by module PRDs" in the Use Cases section.
• NFRs: Aim for the minimum (6 for COMPREHENSIVE) but some policy PRDs may legitimately have fewer if the policies themselves are the non-functional constraints. Document why in a note if under the minimum.
• Dependency Graph: May show which modules consume the policies rather than FR-to-FR build order.

The structural conventions (heading formats, numbering, table columns) still apply without exception. Only the depth of content adapts.

Library & Package PRDs

When the deliverable is a NuGet package, npm package, or shared library consumed by developers (not end-users), several sections need a different lens:

• Personas: The primary personas are developers integrating the package, not end-users of the application. A "Platform Developer" persona describes their integration goals, pain points with current manual setup, and tech level. Secondary personas may include the end-users whose experience the package ultimately enables.
• Use Cases: Frame around developer integration scenarios (adding the package, configuring options, handling edge cases) rather than end-user workflows. The end-user flows belong in the consuming project's PRD, not here.
• Integration Points: Use the Package API Contract variant (see Phase 8b) instead of the microservices "Consumed Services / Exposed Services" format. The "exposed services" are the public API surface — extension methods, middleware, configuration objects, endpoints.
• NFRs: Include package-specific NFRs: binary size, dependency footprint, minimum framework version, API stability guarantees, breaking change policy.
• Phase 0.3 (Consumer Research): Mandatory for library PRDs. Read at least 1-2 consuming projects' integration expectations before drafting requirements. See Phase 0 for details.
• Success Metrics: Measured by developer adoption and integration quality (time-to-integrate, configuration errors, support tickets) rather than end-user business KPIs.

The structural conventions still apply without exception. The shift is in perspective: the "user" is the developer, the "product" is the API surface, and "adoption" means successful integration.

---

Collaborative Model

Phase 0: Prerequisites & Import (Step 0.3: Consumer Research for shared libs)
Phase 1: Document Setup
Phase 2: Problem & Business Context
Phase 3: User Personas (STANDARD+)
  ── PAUSE 1: "Problem, personas, and assumptions right?" ──
Phase 4: Assumptions, Constraints & Risks
Phase 5: Use Cases (COMPREHENSIVE only)
  ── PAUSE 2: "Review each use case individually." ──
Phase 6: Functional Requirements
  ── PAUSE 3: "Review each requirement individually." ──
Phase 7: Non-Functional Requirements
Phase 8: Prioritisation & Dependencies (STANDARD+)
  ── PAUSE 4: "Priorities right? Must Haves truly minimal?" ──
Phase 8b: Integration Points (COMPREHENSIVE only)
Phase 9: Domain Validation (COMPREHENSIVE only)
Phase 10: Self-Review & Approval
  ── PAUSE 5: "Targeted validation questions." ──
Phase 10b: Document Approval (COMPREHENSIVE only)

BRIEF mode skips: Personas (Phase 3), Use Cases (Phase 5), Prioritisation (Phase 8), Integration Points (Phase 8b), Domain Validation (Phase 9), Document Approval (Phase 10b). Uses the streamlined BRIEF template instead.

---

Critical Sequence

Phase 0: Prerequisites

Step 0.1 — Resolve PROJECT_ROOT:

PROJECT_ROOT=$(git rev-parse --show-toplevel)
mkdir -p "${PROJECT_ROOT}/docs/prd/{feature}"

Step 0.2 — Import Upstream Artifacts:

# Brainstorm output
cat "${PROJECT_ROOT}/docs/brainstorm/{feature}/brainstorm.md" 2>/dev/null

# Discovery brief (COMPREHENSIVE mode)
cat "${PROJECT_ROOT}/docs/discovery/{feature}/discovery-brief.md" 2>/dev/null

# Discovery glossary
cat "${PROJECT_ROOT}/docs/discovery/{feature}/glossary.md" 2>/dev/null

# Research brief
cat "${PROJECT_ROOT}/docs/research/{feature}/research-brief.md" 2>/dev/null

Import: problem statement, chosen approach, boundaries, scope classification, kill criteria, domain requirements, actor list, workflow maps, security analysis, compliance checkpoints, glossary terms.

Step 0.3 — Consumer Research (shared libraries/packages only):

If the PRD's deliverable is a shared library, NuGet package, npm package, or SDK consumed by other projects, identify 1-2 consuming projects and read their integration expectations before drafting requirements. This step prevents specifying APIs, protocols, or patterns that contradict what consumers already use.

1. Identify consumers: Ask the user or check the brainstorm for known consuming projects.
2. Read integration docs: For each consumer, read their integration contracts, identity/auth setup,
   or any docs that reference the library being specified.
3. Surface conflicts: Note any discrepancies between what the brainstorm assumed and what consumers
   actually use (e.g., different CSRF mechanisms, different session storage models, naming mismatches).
4. Feed into Phase 4: Add consumer-discovered constraints and assumptions to Phase 4.
   Feed into Phase 6: Let consumer expectations shape FR acceptance criteria.

If no consumers exist yet (greenfield library), skip this step but document the assumption: "No existing consumers — API surface is unconstrained by legacy integration."

Step 0.4 — If No Upstream Exists:

Ask user:

• "What is the feature name and core problem it solves?"
• "Who are the primary users?"
• "What scope? [brief / standard / comprehensive]"

---

Phase 1: Document Setup

# PRD: {Feature Name}

| Field | Value |
|---|---|
| Version | 0.1 |
| Date | {today} |
| Author | {user} |
| Status | Draft |
| Scope | {BRIEF / STANDARD / COMPREHENSIVE} |
| Brainstorm | {link or N/A} |
| Discovery | {link or N/A} |
| Depends On | {links to prerequisite PRDs, or N/A} |

## Document History

| Version | Date | Changes |
|---|---|---|
| 0.1 | {today} | Initial PRD |

Update the Document History table after each major revision — self-review rounds, user feedback incorporation, scope changes. This makes the PRD's evolution auditable.

Step 1.2 — Table of Contents (COMPREHENSIVE, 10+ sections):

For COMPREHENSIVE PRDs that grow beyond 10 sections, add a navigational TOC after the metadata table:

## Table of Contents

1. [Problem Statement](#problem-statement)
2. [Goals](#goals)
3. [User Personas](#user-personas)
4. [Assumptions & Constraints](#assumptions--constraints)
5. [Use Cases](#use-cases)
6. [Functional Requirements](#functional-requirements)
7. [Non-Functional Requirements](#non-functional-requirements)
8. [Integration Points](#integration-points)
9. [Prioritisation](#prioritisation-moscow)
10. [Domain Validation](#domain-validation)
11. [Document Approval](#document-approval)

Update the TOC as sections are added during drafting. This prevents the "scroll-hunting" problem that appears in PRDs exceeding 15 pages.

---

Phase 2: Problem & Business Context

All modes — this is ALWAYS the first substantive section.

Step 2.1 — Problem Statement:

## Problem Statement
{2-3 sentences describing the user problem with specific evidence:
 metrics, support tickets, user research, competitive data.
 Import from brainstorm root problem.}

Impact:
- {Quantified effect 1 — e.g., "23% of support tickets relate to X"}
- {Quantified effect 2}

Why now: {urgency, opportunity, strategic alignment}

Quality check: Does this explain the pain WITHOUT describing the solution?

Step 2.2 — Goals (measurable outcomes, not features):

## Goals
- {Outcome 1 — "Reduce time-to-access from 4.2 days to <1 day"}
- {Outcome 2 — "Eliminate cross-system permission inconsistencies"}

3-5 goals maximum. Each must be measurable. If you can't measure it, it's an aspiration, not a goal.

Step 2.3 — Non-Goals:

## Non-Goals
- {Explicit exclusion with rationale — "Mobile admin (admin tasks are desktop-only)"}

Import from brainstorm anti-requirements.

Step 2.4 — Success Metrics (STANDARD + COMPREHENSIVE):

## Success Metrics
| Metric | Current | Target | By When | How Measured |
|--------|---------|--------|---------|--------------|
| {KPI} | {baseline} | {target} | {date} | {method} |

---

Phase 3: User Personas

STANDARD + COMPREHENSIVE only. BRIEF mode: 1-2 sentences per persona inline with stories.

For each persona (2-4 max):

## User Personas

### P1: {Name}, {Role} (Primary)
"{Archetype description — 'Sarah, IT Manager at a mid-tier mining company'}"
- **Goals:** {What they're trying to accomplish — 2-3 items}
- **Pain Points:** {What frustrates them today — 2-3 items}
- **Current Workaround:** {How they cope without this feature}
- **Success Criteria:** {How they know the feature is working for them}
- **Tech Level:** {Comfortable with admin UIs / developer / non-technical}
- **Frequency:** {How often they'd use this feature}

Import actor list from discovery brief if available. Personas inform assumptions and constraints in Phase 4 — a "non-technical" persona constrains UI complexity, a "developer" persona may allow CLI-only interfaces.

PAUSE 1: Validate problem, personas, and context (Guided Review — Pattern 5)

Step 1 — Problem + Goals + Non-Goals: Present the problem statement, goals, and non-goals as formatted markdown, then:

AskUserQuestion:
  question: "Does the problem statement accurately describe the pain? Are goals measurable and non-goals clear?"
  header: "Problem"
  multiSelect: false
  options:
    - label: "Approved"
      description: "Problem framing, goals, and non-goals are correct."
    - label: "Needs revision"
      description: "Something needs changing — I'll provide notes."
    - label: "Skip for now"
      description: "Come back to this section later."

If "Needs revision": collect notes, iterate on the section, then re-present and re-ask.

Step 2 — Personas: Present personas as formatted markdown, then:

AskUserQuestion:
  question: "Do these personas match real users? Are their pain points and success criteria accurate?"
  header: "Personas"
  multiSelect: false
  options:
    - label: "Approved"
      description: "Personas reflect real users and their needs."
    - label: "Needs revision"
      description: "Something needs changing — I'll provide notes."
    - label: "Skip for now"
      description: "Come back to this section later."

If "Needs revision": collect notes, iterate, re-present and re-ask.

Do not proceed until the user confirms the problem framing and personas are right. Everything downstream depends on this.

---

Phase 4: Assumptions, Constraints & Risks

All modes. This section prevents the most common PRD failures — undocumented assumptions that blow up later.

Step 4.1 — Assumptions:

Things we're taking for granted. If any prove false, requirements may need to change. Assumptions should be informed by the personas from Phase 3.

Bullet format (minimum):

## Assumptions
- **A1:** The existing API can handle the additional load
- **A2:** P1 persona (IT Manager) has admin access to configure this feature

Table format (richer — preferred when assumptions have validation plans):

## Assumptions

| # | Assumption | Impact if Wrong | How to Validate |
|---|-----------|----------------|-----------------|
| **A1:** | The existing API can handle the additional load | FRs 3-5 need redesign for async | Load test before MVP |
| **A2:** | P1 has admin access to configure | Needs new admin provisioning FR | Verify with IT ops |

Both formats are acceptable. The **A{n}:** prefix is required in either format. The table format preserves "Impact if Wrong" and "How to Validate" context that bullets lose — use it for STANDARD+ PRDs when assumptions carry significant risk.

Step 4.2 — Constraints:

Hard limits that shape what's possible.

## Constraints
- {Technical: "Must work within existing database schema"}
- {Business: "Budget limited to current team capacity"}
- {Regulatory: "Must comply with POPIA data residency requirements"}
- {Timeline: "Must ship before contract renewal in Q3"}

Step 4.3 — Risks & Open Questions:

Track unknowns throughout the PRD process. Update this section as questions surface in later phases.

## Risks
| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| {What could go wrong} | Low/Med/High | Low/Med/High | {How to reduce} |

## Open Questions

| # | Question | Context | Status | Decision | Owner |
|---|----------|---------|--------|----------|-------|
| 1 | {Question} | {Why it matters} | Open / Resolved | {Decision if resolved} | {Who decides} |
| 2 | {Question} | {Context} | Open | — | {Owner} |

COMPREHENSIVE mode: Open Questions become decision gates — questions that must be resolved before implementation. Track resolution status through PRD revisions. The AMPS PRD tracked 15 questions with resolution status across 4 versions; unresolved questions at implementation time caused rework.

---

Phase 5: Use Cases (COMPREHENSIVE mode only)

BRIEF/STANDARD modes skip this phase — user stories in Phase 6 are sufficient.

Use cases are standalone files, not sections inside the PRD. This prevents the PRD from becoming a monolith (the identity project's 134KB PRD taught us this). Each use case is 3-15KB — manageable, reviewable, and referenceable by design and plan docs independently.

File location depends on scope:

• Feature-scoped use cases (most common) → docs/prd/{feature}/use-cases/ — colocated with the PRD they belong to
• Cross-module use cases (span multiple features/aggregates) → docs/use-cases/ — shared common folder

# Feature-scoped use cases (default)
mkdir -p "${PROJECT_ROOT}/docs/prd/{feature}/use-cases"

# Cross-module use cases (only when a UC spans multiple features)
mkdir -p "${PROJECT_ROOT}/docs/use-cases"

Step 5.1 — Identify Use Case Set:

Map personas and workflows from discovery to 5-10 use cases. Each use case represents a complete user goal, not a single action.

| UC ID | Goal | Primary Actor | Depth Tier | Status |
|-------|------|---------------|-----------|--------|
| UC-{MODULE}-001 | {Goal as active verb phrase} | {Persona} | Tier 1/2/3 | Draft |

Depth tiers:

• Tier 1 — Full Cockburn format: preconditions, success/failure guarantees, step-by-step scenario, extensions, failure paths. For core flows that define the feature.
• Tier 2 — Standard format: scenario flow with steps, postconditions, failure paths. For important but less complex flows.
• Tier 3 — Index entry with links to relevant guide sections and endpoint lists. For flows that are heavily dependent on external configuration or environment.

Step 5.2 — Write Each Use Case:

Save each to:

• Feature-scoped: ${PROJECT_ROOT}/docs/prd/{feature}/use-cases/UC-{MODULE}-{NNN}-{slug}.md
• Cross-module: ${PROJECT_ROOT}/docs/use-cases/UC-{MODULE}-{NNN}-{slug}.md

Default to feature-scoped. Only use the common folder when a use case genuinely spans multiple features or aggregate roots.

# UC-{MODULE}-{NNN}: {Goal as Active Verb Phrase}

> {One-sentence summary of what this use case establishes.}

## Metadata

| Field | Value |
|-------|-------|
| **Actor** | {Persona from Phase 3} |
| **Trigger** | {Event that starts this use case} |
| **Preconditions** | {State that must be true BEFORE the use case starts} |
| **Depth Tier** | Tier {1/2/3} |
| **Status** | Draft |
| **Related Docs** | {Links to PRD sections, guide sections, other UCs} |

## Scenario Flow

### Phase 1: {Phase Name}

| Step | Action | Details |
|------|--------|---------|
| 1.1 | {Actor or System} {action at user-intention level} | {Specifics — validation rules, API routes, business logic} |
| 1.2 | ... | ... |

### Phase 2: {Phase Name}
...

## Postconditions

- {Observable state of the world when goal is achieved}

## Failure Paths

| Failure | Behavior |
|---------|----------|
| {What goes wrong} | {How the system responds — specific error, rollback, guarantee} |

## Known Deferred Edges

- {Edge case intentionally excluded from v1 with rationale}

Tier 1 use cases add these sections:

## Minimal Guarantee (on failure)

{What the system guarantees even if the use case fails —
 e.g., "No data corrupted, audit log records the attempt"}

## Business Rules

| Rule ID | Rule | Parameters |
|---------|------|-----------|
| BR-{MODULE}-{NNN} | {Specific rule} | {Thresholds, limits, constraints} |

Guidelines:

• 3-9 steps per phase — write at user-intention level, not UI-action level
• Every step that can fail gets a failure path entry
• Use the table format for scenario steps (not numbered prose) — it's scannable and supports detail columns
• Reference other UCs for flows that continue across use cases

Step 5.3 — Reference Use Cases in PRD:

Add a use case index section to the PRD that links to the standalone files:

## Use Cases

Feature-scoped use cases are in `docs/prd/{feature}/use-cases/`.
Cross-module use cases are in `docs/use-cases/`.

| UC ID | Title | Depth | Actor | Scope | Status |
|-------|-------|-------|-------|-------|--------|
| [UC-{MODULE}-001](use-cases/UC-{MODULE}-001-{slug}.md) | {title} | Tier 1 | {actor} | Feature | Draft |
| [UC-{MODULE}-002](../../use-cases/UC-{MODULE}-002-{slug}.md) | {title} | Tier 2 | {actor} | Cross-module | Draft |

Step 5.4 — Optional: Traceability Index (COMPREHENSIVE, 5+ use cases):

For projects with 5+ use cases, create a traceability index that maps scenarios to implementation evidence:

Save to: ${PROJECT_ROOT}/docs/prd/{feature}/use-cases/traceability-index.md

For cross-module use cases, maintain a separate index at ${PROJECT_ROOT}/docs/use-cases/traceability-index.md.

# Traceability Index

> Scenario-level index of supported use cases.
> Tracks: which scenarios are implemented, where documented, what automated evidence exists.

| Scenario ID | Scenario Name | Depth Tier | Status | Primary Doc | Test Evidence | Open Gaps |
|-------------|--------------|------------|--------|-------------|---------------|-----------|
| UC-{MODULE}-001 | {title} | Tier 1 | {status} | [link] | {test files} | {gaps} |

This is a living document — update it as use cases move from Draft → Implemented.

PAUSE 2: Review each use case (Guided Review — Pattern 5)

Review each use case individually with the user. For each UC:

Step 1 — Present full detail: Show the use case summary as formatted markdown — UC ID, goal, actor, trigger, scenario flow overview, postconditions, and failure paths.

Step 2 — Ask for verdict:

AskUserQuestion:
  question: "Review this use case."
  header: "UC Review"
  multiSelect: false
  options:
    - label: "Approve"
      description: "Use case is good as-is. Move to the next one."
    - label: "Revise"
      description: "Needs changes — I'll provide notes."
    - label: "Remove"
      description: "Drop this use case entirely."
    - label: "Skip for now"
      description: "Come back to this after reviewing the rest."

Step 3 — Handle verdict:

• Approve: Mark as approved, move to next UC.
• Revise: Collect the user's notes, revise the use case file, re-present it, and re-ask.

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->