Prd

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  {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:

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: dirkkok101
• Source: dirkkok101/skills
• License: MIT

Install and usage instructions live in the source repository linked above.