prd

name	prd
description	Use when starting a business feature that needs requirements, when user says "write requirements", "create PRD", "define user stories", or after brainstorm/discovery approval.
argument-hint	[feature name or brainstorm reference]

PRD: Problem → Formal Requirements

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.
• Remove: Delete the UC file and remove it from the index table. Move to next UC.
• Skip for now: Queue for a second pass after all other UCs are reviewed.

Step 4 — Second pass: After all UCs have been reviewed, re-present any skipped use cases and repeat Steps 1-3 for each.

This per-use-case approach mirrors the FR review process (PAUSE 3) and ensures each scenario gets focused attention before downstream skills consume them.

---

Phase 6: Functional Requirements

All modes. BRIEF: 3-5 stories. STANDARD: 8-15 stories. COMPREHENSIVE: 15-25 stories.

## Functional Requirements

### Epic: {Feature Area}

#### FR-{MODULE}-{DESCRIPTIVE-NAME}: {Title}
Priority: Must / Should / Could / Won't
Complexity: S / M / L / XL
Related: UC-{MODULE}-001 (COMPREHENSIVE mode)

As a {persona from Phase 3},
I want to {action},
So that {benefit}.

Acceptance Criteria:
  Given {precondition}
  When {action}
  Then {expected result}

  Given {error condition}
  When {invalid action}
  Then {error handling behavior}

Stable ID convention: Use descriptive IDs based on feature area, not sequential numbers. FR-APP-REGISTER is more stable than FR-APP-001 — it survives when requirements are added or removed. Downstream artifacts (design, plan, beads, tests) reference these IDs, so stability prevents cascade updates.

COMPREHENSIVE mode adds Security and Compliance Criteria on applicable stories:

Security Criteria: (from discovery security analysis)
  - {Requirement — "Secrets hashed before storage"}
  - {Requirement — "Redirect URIs validated against exact match"}

Compliance Criteria: (from discovery compliance checkpoints)
  - POPIA: {Requirement — "Metadata includes processing purpose"}
  - SOC 2: {Requirement — "All CRUD operations logged with actor and timestamp"}

Systematic Edge Case Elicitation

After drafting the initial requirements, probe for edge cases — focus on Must Have FRs and complex interactions first. Don't exhaustively probe every FR; prioritize where bugs would be most costly.

For prioritized FRs, ask:

• Duplicates: What if the user does this twice? What if the same data already exists?
• Boundaries: What if the input is empty? Maximum length? Zero? Negative?
• Concurrency: What if two users do this simultaneously?
• Permissions: What if the user doesn't have access? What about partial access?
• State: What if a dependency is unavailable? What about stale data?
• Lifecycle: What about deletion? Archival? Migration of existing data?

Each discovered edge case becomes either a new acceptance criterion on an existing FR, or a new FR if it's significant enough.

Requirement Quality Check

Before presenting requirements to the user, scan for these quality issues:

Ambiguity words — flag any requirement containing: "appropriate", "reasonable", "quickly", "user-friendly", "intuitive", "properly", "sufficient", "as needed", "etc.", "and/or". These words mask undecided requirements. Replace each with a specific, testable statement.

Testability — every acceptance criterion must be verifiable by a test. "The system should handle errors gracefully" is not testable. "Given a network timeout, when the user submits, then a retry dialog appears within 2 seconds" is testable.

Independence — each FR should be deliverable and valuable on its own. If FR-X only makes sense with FR-Y, consider merging them or making the dependency explicit.

PAUSE 3: Validate requirements (Guided Review — Pattern 5, adaptive pacing)

Start by reviewing each functional requirement individually. After the 3rd consecutive approval without revision, offer the user a pacing choice:

AskUserQuestion:
  question: "You've approved 3 FRs without changes. How would you like to review the remaining {N} requirements?"
  header: "Review Pacing"
  multiSelect: false
  options:
    - label: "Continue one-at-a-time"
      description: "Keep reviewing each FR individually."
    - label: "Batch the rest"
      description: "Present remaining FRs together for a single review pass."

Individual review (default, and first 3 FRs always):

Step 1 — Present full detail: Show the single requirement as formatted markdown with full FR detail — user story, acceptance criteria, priority, and complexity.

Step 2 — Ask for verdict:

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

Step 3 — Handle verdict:

• Approve: Record as approved, move to next FR. Track consecutive approval count.
• Revise: Collect the user's notes (from "Other" field or follow-up), revise the requirement, re-present it, and re-ask. Reset consecutive approval count.
• Remove: Drop the FR from the document with a brief rationale note. Move to next FR.
• Skip for now: Queue for a second pass after all other FRs are reviewed.

Batch review (if user chose "Batch the rest"):

Present all remaining FRs as formatted markdown in one block, then:

AskUserQuestion:
  question: "Review the remaining requirements. Flag any that need revision by name."
  header: "FR Batch Review"
  multiSelect: true
  options:
    - label: "All approved"
      description: "All remaining requirements are good as-is."
    - label: "FR-{MODULE}-{NAME-1}"
      description: "Needs revision — I'll provide notes."
    - label: "FR-{MODULE}-{NAME-2}"
      description: "Needs revision — I'll provide notes."

For any flagged FRs, collect notes, revise, and re-present individually.

Step 4 — Second pass: After all FRs have been reviewed, re-present any skipped requirements and repeat Steps 1-3 for each.

This adaptive approach gives focused attention where needed while respecting the user's review velocity.

---

Phase 7: Non-Functional Requirements

All modes. BRIEF: 2-3 NFRs. STANDARD: 4-6 NFRs. COMPREHENSIVE: 6-10 NFRs.

## Non-Functional Requirements

### NFR-{MODULE}-{DESCRIPTIVE-NAME}: {Title}
Category: Performance / Security / Scalability / Data / Accessibility
Target: {Specific measurable target — "95th percentile < 200ms"}
Load Condition: {Context — "100 concurrent users per tenant"}
Measurement: {How to verify}
Rationale: {Why this target — trace to problem statement, success metrics, or persona needs}

Categories to consider:

1. Performance — API response time, page load, batch throughput
2. Security — Authentication, encryption, audit logging, rate limiting
3. Scalability — Concurrent users, data volume, geographic distribution
4. Data — Retention, backup, deletion, migration
5. Accessibility — WCAG 2.1 AA, keyboard navigation, screen readers

Every NFR has a number, not an adjective. "Fast" is not a requirement. "< 200ms P95" is. Every NFR target should trace to either the problem statement, a success metric, or a persona need — arbitrary targets are waste.

Mandatory NFR: Audit coverage. Any module with state-changing operations (create, update, delete, status transitions) MUST include an audit NFR (e.g., NFR-{MODULE}-AUDIT) specifying: 100% mutation coverage, actor ID + timestamp + entity ID in every log entry, and the audit event type naming convention ({entity_type}.{action}).

Minimum counts are strict. COMPREHENSIVE requires at least 6 NFRs — not 5, not "around 6". Count them before finalizing. If you have fewer than 6, add NFRs for categories you haven't covered (performance, security, scalability, data, accessibility).

---

Phase 8: Prioritisation & Dependencies

STANDARD + COMPREHENSIVE only.

## Prioritisation (MoSCoW)

### Must Have (MVP)
- FR-{MODULE}-{NAME}: {title}
{5-10 items. Without these, the feature doesn't solve the problem.}

### Should Have (v1)
- FR-{MODULE}-{NAME}: {title}
{Significant value but not blocking MVP. Could slip to v1.1.}

### Could Have (Future)
- {Enhancement idea}

### Won't Have (Yet)
- {Excluded item} — Reason: {why}
{Explicitly out of scope. Prevents scope creep.}

## Dependency Graph

  FR-REGISTER ──> FR-VALIDATE ──> FR-PROVISION
       |                              |
       +──> FR-CONFIGURE          FR-NOTIFY

{ASCII diagram using ──> arrows showing FR-to-FR dependencies.
 Always include this diagram — it makes implementation ordering visible.
 Show which FRs must be built before others can start.}

PAUSE 4: Validate priorities (Guided Review — Pattern 5)

Step 1 — Review Must Haves: Present the Must Have list as formatted markdown, then:

AskUserQuestion:
  question: "Which Must Have items could actually be Should Have? (Select items to downgrade)"
  header: "Priorities"
  multiSelect: true
  options:
    - label: "FR-{MODULE}-{NAME-1}"
      description: "{Title}"
    - label: "FR-{MODULE}-{NAME-2}"
      description: "{Title}"
    - label: "FR-{MODULE}-{NAME-3}"
      description: "{Title}"

For selected items, move them to Should Have. If no items selected, Must Haves are confirmed as-is.

Step 2 — Review Should Haves: Present the Should Have list as formatted markdown, then:

AskUserQuestion:
  question: "Should any of these be upgraded to Must Have? (Select items to upgrade)"
  header: "Upgrades"
  multiSelect: true
  options:
    - label: "FR-{MODULE}-{NAME-1}"
      description: "{Title}"
    - label: "FR-{MODULE}-{NAME-2}"
      description: "{Title}"

For selected items, move them to Must Have.

Priority decisions shape what gets built first. Getting them wrong means building the wrong thing.

---

Phase 8b: Integration Points (COMPREHENSIVE only)

For platform services that other systems consume. If this feature exposes APIs, events, or data that downstream systems depend on, document the integration surface at the PRD level. This prevents the common failure mode where integration requirements are discovered during implementation rather than planning.

## Integration Points

### Consumed Services
| Service | Purpose | Failure Impact |
|---------|---------|---------------|
| {Upstream service} | {What this feature needs from it} | {What happens if unavailable} |

### Exposed Services
| Interface | Consumers | Contract Stability |
|-----------|-----------|-------------------|
| {API/Event/Data this feature provides} | {Who depends on it} | {Stable / Evolving / Experimental} |

### Integration NFRs
- {Latency requirements for cross-service calls}
- {Retry/circuit-breaker expectations}
- {Data consistency guarantees across service boundaries}

This section feeds directly into the technical design's API surface and the plan's dependency graph. Mark Contract Stability clearly — "Stable" means downstream consumers can rely on it without coordination; "Evolving" means breaking changes require coordination.

Package API Contract Variant (for NuGet/npm packages and shared libraries)

When the PRD's deliverable is a shared library or package rather than a microservice, the "Consumed Services / Exposed Services" table format is a poor fit. Use the Package API Contract format instead:

## Integration Points — Package API Contract

### Public API Surface
| API | Type | Purpose | Stability |
|-----|------|---------|-----------|
| `AddMyPackage()` | Extension method | Registers all package services in DI | Stable |
| `UseMyPackage()` | Middleware | Adds package middleware pipeline | Stable |
| `/api/health` | Endpoint | Health check endpoint | Stable |
| `PackageOptions` | Configuration | Consumer-provided settings | Evolving |

### Consumer Integration Pattern
{How a consuming project adds and configures the package — 5-10 lines of representative code showing the expected DI registration, middleware order, and configuration.}

### Package Dependencies
| Dependency | Version Constraint | Why |
|------------|-------------------|-----|
| {NuGet/npm package} | {range} | {purpose} |

### Consumer Responsibilities
- {What the consumer must provide — e.g., "Redis connection for session storage"}
- {What the consumer must configure — e.g., "OIDC authority URL in BffOptions"}
- {Infrastructure the consumer owns — e.g., "Data protection key ring"}

Use this variant whenever the deliverable is installed via a package manager rather than deployed as a standalone service. The standard "Consumed Services / Exposed Services" format remains the default for microservice PRDs.

---

Phase 9: Domain Validation (COMPREHENSIVE only)

Verify discovery requirements are fully covered:

## Domain Validation
- [ ] All IN SCOPE discovery requirements (DR-*) mapped to at least one FR?
- [ ] Security criteria present on all security-sensitive stories?
- [ ] Compliance criteria present where regulations apply?
- [ ] All integration points from discovery have corresponding NFRs?
- [ ] All actors from discovery have at least one use case (in docs/prd/{feature}/use-cases/ or docs/use-cases/)?
- [ ] All use case files cross-reference back to the PRD?
- [ ] Cross-PRD alignment verified (if Depends On references another PRD)?

### Coverage Matrix
| Discovery Req | Mapped FR | Use Case | Status |
|--------------|-----------|----------|--------|
| DR-{MODULE}-{NAME} | FR-{MODULE}-{NAME} | UC-{MODULE}-{NNN} | Covered |
| DR-{MODULE}-{NAME} | — | — | Gap (deferred to v2) |

Cross-PRD Alignment (when Depends On is not N/A)

When the metadata table's Depends On field references another PRD, perform an explicit cross-check before finalizing:

1. Read the parent PRD's Functional Requirements section.
2. Identify every FR in the parent PRD that references or delegates to THIS feature.
   (e.g., FR-AUTH-BFF-FLOW in a parent authentication PRD that delegates BFF behavior to this PRD)
3. For each parent FR:
   - List its acceptance criteria.
   - Map each criterion to a specific FR in THIS PRD that covers it.
   - Flag any parent criterion that has no coverage in this PRD.
4. Document the mapping:

### Cross-PRD Alignment

Parent PRD: {link}

| Parent FR | Parent Criterion | Covered By | Status |
|-----------|-----------------|------------|--------|
| FR-AUTH-BFF-FLOW | AC: Token exchange via back-channel | FR-BFF-TOKEN-EXCHANGE | Covered |
| FR-AUTH-BFF-FLOW | AC: Session cookie httpOnly + secure | FR-BFF-SESSION-MGMT | Covered |
| FR-AUTH-BFF-FLOW | AC: CSRF protection on mutations | FR-BFF-CSRF | Covered |
| FR-AUTH-BFF-FLOW | AC: Silent refresh before expiry | — | Gap — add FR or document deferral |

Any gaps must be resolved before approval: either add the missing FR, or document the deferral with rationale in the Coverage Matrix.

---

Phase 10: Self-Review & Approval

1 thorough round. Fix issues found. Re-check only the fixes.

The previous "2 consecutive clean rounds" approach added no value — if the first round's fixes are correct, the second round is a rubber stamp. Instead: one focused pass through all themes, fix everything found, then verify only the changed sections.

Known limitation: Self-review is performed by the same agent that wrote the PRD. Mitigate by following themes strictly as a checklist, and by asking the user targeted questions where you're least confident.

Review Themes

1. Completeness — All personas covered? All stories have acceptance criteria? All must-haves prioritised? (COMPREHENSIVE: FR → UC → Persona chain complete? Discovery requirements covered?)
2. Clarity & Testability — Could a developer implement each FR without asking questions? Every criterion verifiable by a test? No ambiguity words?
3. Scope Discipline — Nothing exceeds brainstorm boundaries? Won't-Have items have reasoning? Must Have list truly minimal (≤10)?
4. Assumptions & Risks — All assumptions documented? Would any false assumption invalidate requirements? Open questions flagged, not silently decided?
5. Edge Cases — Failure paths considered for Must Have FRs? Concurrent access, empty states, permission boundaries probed?

Kill Criteria Check

Review brainstorm kill criteria against PRD findings. Has requirements writing revealed complexity that exceeds the brainstorm's budget? If any kill criterion is triggered, flag it:

"PRD finding {X} triggers kill criterion {Y} from the brainstorm. Options: (1) Adjust scope, (2) Adjust kill criteria, (3) Abandon."

Quality Scan

After thematic review, do a final scan for:

• Ambiguity words (see Phase 6 quality check list)
• Untestable criteria
• Open questions that are still unresolved (these should be flagged, not silently decided by the agent)
• Missing error paths in acceptance criteria
• NFR targets without rationale tracing to problem/metrics

PAUSE 5: User validation questions (Combined Gate — Pattern 4)

After self-review, ask all three validation questions simultaneously:

AskUserQuestion:
  questions:
    - question: "Which acceptance criteria are you LEAST confident about?"
      header: "Confidence"
      multiSelect: true
      options:
        - label: "FR-{MODULE}-{NAME-1}"
          description: "{Title} — most complex/risky FR"
        - label: "FR-{MODULE}-{NAME-2}"
          description: "{Title} — most complex/risky FR"
        - label: "FR-{MODULE}-{NAME-3}"
          description: "{Title} — most complex/risky FR"
    - question: "Are there assumptions that might not hold?"
      header: "Assumptions"
      multiSelect: false
      options:
        - label: "All assumptions valid (Recommended)"
          description: "No concerns about the documented assumptions."
        - label: "Some are risky"
          description: "One or more assumptions may not hold — I'll provide notes."
        - label: "Need to investigate"
          description: "We should validate specific assumptions before proceeding."
    - question: "Anything in Won't Have you're uncomfortable deferring?"  # STANDARD+ only — skip in BRIEF (no prioritisation section)
      header: "Deferrals"
      multiSelect: false
      options:
        - label: "All fine (Recommended)"
          description: "Won't Have items are correctly scoped out."
        - label: "Some should be reconsidered"
          description: "One or more Won't Have items may need to move into scope."

Select 3-4 of the most complex or risky FRs for the Confidence question options. For flagged items, dig deeper into specific concerns before finalizing.

---

Phase 10b: Document Approval (COMPREHENSIVE only)

For COMPREHENSIVE PRDs with multiple stakeholders, add a formal approval section. This creates an auditable record of who signed off and prevents the "I thought you approved it" problem.

## Document Approval

| Role | Name | Status | Date |
|------|------|--------|------|
| Product Owner | {name} | Approved / Pending | {date} |
| Tech Lead | {name} | Approved / Pending | {date} |
| Domain Expert | {name} | Approved / Pending | {date} |

**Approval means:** Requirements are correct and complete enough to begin technical design. It does NOT mean requirements are frozen — the Document History table tracks subsequent changes.

---

BRIEF Mode Template

For BRIEF scope, skip Phases 3, 5, 8, 8b, 9, 10b. Produce this streamlined one-page format:

# PRD: {Feature Name} (Brief)

**Date:** {today} | **Scope:** BRIEF | **Status:** Draft

## Problem
{2-3 sentences — what's broken and for whom}

## Goals
- {Measurable outcome 1}
- {Measurable outcome 2}

## Non-Goals
- {What we're explicitly NOT doing}

## Assumptions
- {Key assumptions that could change scope if wrong}

## Requirements

### FR-{MODULE}-{NAME}: {Title} [Must]
As a {role}, I want {action}, so that {benefit}.
- Given {X}, When {Y}, Then {Z}
- Given {error}, When {invalid}, Then {handled}

### FR-{MODULE}-{NAME}: {Title} [Must]
...

{3-5 stories total}

## NFRs
- NFR-{MODULE}-{NAME}: {target with number and rationale}

## Open Questions
- {Anything unresolved}

---

PRD Output

Save to:

• ${PROJECT_ROOT}/docs/prd/{feature}/prd.md — the PRD itself
• ${PROJECT_ROOT}/docs/prd/{feature}/use-cases/UC-{MODULE}-{NNN}-{slug}.md — feature-scoped use cases (COMPREHENSIVE only)
• ${PROJECT_ROOT}/docs/use-cases/UC-{MODULE}-{NNN}-{slug}.md — cross-module use cases that span features/aggregates
• ${PROJECT_ROOT}/docs/prd/{feature}/use-cases/traceability-index.md — optional traceability index (COMPREHENSIVE, 5+ UCs)

The PRD follows the phase order: Document History → Problem → Personas → Assumptions & Constraints → Use Case Index → FRs → NFRs → Prioritisation → Validation

Use cases are standalone files referenced by the PRD, not embedded in it. Feature-scoped use cases live alongside their PRD in docs/prd/{feature}/use-cases/; cross-module use cases that span multiple features or aggregate roots go in the shared docs/use-cases/ folder. This keeps related artifacts colocated while the common folder signals cross-cutting concerns.

---

Traceability Rules

• Every FR maps to at least one persona
• COMPREHENSIVE: every FR maps to at least one UC
• Every FR has testable acceptance criteria in Given/When/Then
• Security criteria on stories touching auth, PII, or destructive operations
• Compliance criteria on stories touching regulated data
• Stable FR IDs survive requirement additions/removals
• NFR targets trace to problem statement, success metrics, or persona needs

---

Exit Signals

Signal	Meaning	Next Action
"prd approved"	PRD complete and ready	Proceed to /technical-design
"refine"	Gaps or clarity issues	Return to relevant phases
"park"	Save for later	Archive; user resumes later
"abandon"	Don't build this feature	Document decision rationale

When exiting, update PRD metadata: Status, Next Step, Completion Date.

---

Structural Conventions (Non-Negotiable)

Every PRD produced by this skill must follow these conventions exactly. Only content varies between PRDs — structure, naming, and formatting are fixed.

Mandatory Sections (COMPREHENSIVE)

Every COMPREHENSIVE PRD must contain ALL of these H2 sections in this order:

1. ## Document History
2. ## Table of Contents
3. ## Problem Statement
4. ## Goals
5. ## Non-Goals
6. ## Success Metrics
7. ## User Personas
8. ## Assumptions & Constraints
9. ## Use Cases
10. ## Functional Requirements
11. ## Non-Functional Requirements
12. ## Integration Points
13. ## Prioritisation (MoSCoW)
14. ## Domain Validation
15. ## Document Approval

Optional H2 sections (add when relevant, after Document Approval):

• ## Appendix: API Endpoint Summary (Indicative)
• ## Appendix: Database Tables (Indicative)

Naming & Numbering Conventions

Element	Format	Example
Goals	- **G{n}:** {text}	- **G1:** Reduce time-to-access
Non-Goals	- **NG{n}:** {text} — Reason: {why}	- **NG1:** Mobile — Reason: desktop-only
Assumptions	- **A{n}:** {text} or table with **A{n}:** in first column	- **A1:** API handles load
Constraints	- **C{n}:** {text} or table with **C{n}:** in first column	- **C1:** Must use existing schema
FR IDs	FR-{MODULE}-{DESCRIPTIVE-NAME}	FR-APP-REGISTER
NFR IDs	NFR-{MODULE}-{DESCRIPTIVE-NAME}	NFR-APP-RESPONSE-TIME
UC IDs	UC-{MODULE}-{NNN}	UC-APP-001
Personas	### P{n}: {Role Title}	### P1: Platform Administrator (Primary)
Epics	### Epic: {Name}	### Epic: User Lifecycle

Heading Levels (Fixed)

Element	Level	Example
Sections	H2	## Problem Statement
Epics	H3	### Epic: User Lifecycle
Personas	H3	### P1: Platform Administrator
NFRs	H3	### NFR-APP-LATENCY: API Response Time
FRs	H4	#### FR-APP-SAVE: Save Application
Sub-sections	H3	### Assumptions, ### Constraints, ### Risks, ### Open Questions

Persona Sub-Fields (All 6 Mandatory)

Every primary or secondary persona MUST have exactly these 6 bold sub-fields:

- **Goals:** {2-3 items}
- **Pain Points:** {2-3 items}
- **Current Workaround:** {how they cope today}
- **Success Criteria:** {how they know the feature works}
- **Tech Level:** {description}
- **Frequency:** {how often they use this}

Reference Personas (Read-Only Involvement)

When a persona's involvement in the module is read-only (viewing dashboards, receiving notifications, consuming reports) and their full definition exists in a project-level personas document, use the lightweight reference format instead of the full 6-field definition:

### P{n}: {Role Title} (Reference)
> See [project personas](../../personas.md) for full definition.
- **Module interaction:** {1-2 sentences describing how this persona uses THIS module specifically}

This avoids writing generic 6-field definitions for personas who only consume data. The reference must point to an existing project persona document. If no project persona doc exists, use the full format.

FR Body Structure (Fixed Format)

#### FR-{MODULE}-{NAME}: {Title}
Priority: Must / Should / Could / Won't
Complexity: S / M / L / XL
Related: UC-{MODULE}-{NNN}

As a {persona} (P{n}),
I want to {action},
So that {benefit}.

Acceptance Criteria:
  Given {precondition}
  When {action}
  Then {expected result}

Security Criteria:
  - {requirement}

Lines Priority, Complexity, Related appear one per line, no bold. Acceptance Criteria are indented 2 spaces. Security Criteria required on any FR that modifies data, touches auth, or handles PII. Compliance Criteria required on any FR touching regulated data.

NFR Body Structure (Fixed Format)

### NFR-{MODULE}-{NAME}: {Title}
Category: Performance / Security / Scalability / Data / Accessibility
Target: {specific number — "P95 < 200ms", not "fast"}
Load Condition: {context}
Measurement: {how to verify}
Rationale: {traces to problem statement, success metrics, or persona needs}

Table Formats (Fixed Columns)

Table	Columns (in order)
Success Metrics	Metric | Current | Target | By When | How Measured
Risks	Risk | Likelihood | Impact | Mitigation
Open Questions	# | Question | Context | Status | Decision | Owner
Document Approval	Role | Name | Status | Date

MoSCoW Headings (Fixed Text)

### Must Have (MVP)
### Should Have (v1)
### Could Have (Future)
### Won't Have (Yet)

Integration Points Sub-Headings (Fixed Text)

### Consumed Services
### Exposed Services
### Integration NFRs

Strict Rules

1. FR IDs are DESCRIPTIVE, never sequential numbers (FR-APP-REGISTER not FR-APP-001)
2. NFR targets contain specific numbers, never adjectives
3. No ambiguity words in acceptance criteria: "appropriate", "reasonable", "quickly", "user-friendly", "intuitive", "properly", "sufficient", "as needed", "etc.", "and/or"
4. At least one error/edge case acceptance criterion per Must Have FR
5. Must Have list ≤ 10 items
6. Won't Have items always have a "Reason:" rationale
7. Dependency Graph section uses ASCII ──> arrows showing FR-to-FR build order

---

Anti-Patterns

The Monologue — Agent generates entire PRD, dumps it for approval. Instead, pause and validate at each phase. The user knows things the agent doesn't.

Solution-First — Writing features before establishing the problem. If Phase 2 doesn't hurt to read, you haven't described a real problem.

Vague Criteria — "System should be fast" or "handle errors appropriately". Every requirement needs a number or a specific behavior. Flag ambiguity words.

Happy Path Only — Acceptance criteria that only cover success. Every Must Have FR needs at least one error/edge case criterion. Use the edge case elicitation checklist.

The Kitchen Sink — v1 through v10 in one doc. Strict MoSCoW with Won't Have. If the Must Have list has more than 10 items, some of them aren't Must Haves.

Silent Assumptions — Taking things for granted without documenting them. If an assumption proves false and there's no record, nobody knows which requirements to revisit.

Orphan Stories — Stories not linked to personas or use cases. If you can't name the persona, the requirement may not solve a real problem.

Arbitrary NFR Targets — Setting performance or scalability targets without rationale. "P95 < 200ms" means nothing without knowing the current baseline and why that number matters. Every target traces to a real need.

Monolith PRD — Embedding use cases, detailed scenarios, and gap analysis inline in the PRD. A 134KB PRD is unreadable and unmaintainable. Use cases are standalone files. The PRD references them by link and index table. Each artifact should be reviewable on its own.

Undocumented Evolution — Making significant changes to the PRD without recording what changed and why. The Document History table exists for this — update it after each adversarial review round, scope change, or user feedback incorporation.

---

Living Document Convention

PRDs may outlive the sprint they were written in. When architecture changes or new learnings invalidate parts of the PRD, add a Legacy Update notice rather than silently rewriting history:

> **Legacy Update ({date}):** {Section X} was revised because {reason}.
> Original requirement was {old}; updated to {new} based on {evidence}.

This preserves the decision trail — anyone reading the PRD can see what changed and why, which is critical for long-lived features that evolve across multiple releases.

---

Skill Version: 3.10 — Version History