Document Architecture
Organize every PRD around these core sections. Adapt the depth of each section to the complexity of the initiative.
The Problem Frame
Ground the entire document in a clearly articulated problem:
- Identify the specific user pain point in concrete, observable terms
- Quantify who suffers from this problem and at what frequency
- Articulate the consequences of inaction: lost revenue, user attrition, operational burden, or competitive exposure
- Anchor claims in evidence drawn from support tickets, user interviews, behavioral data, or market signals
Desired Outcomes
Translate the problem into 3-5 measurable targets:
- Frame each outcome around observable change: behavior shifts, efficiency gains, error reduction
- Separate user-facing outcomes (what improves for the customer) from organizational outcomes (what the business gains)
- Express outcomes as results rather than deliverables: "cut onboarding duration by half" instead of "redesign the onboarding flow"
- Every outcome must answer: "what evidence will confirm we achieved this?"
Boundaries and Exclusions
Prevent runaway scope by documenting 3-5 items that are deliberately excluded:
- Name adjacent capabilities that will not be addressed in this iteration
- Provide a brief rationale for each exclusion: insufficient data, low leverage, better suited to a follow-up phase, or separate workstream
- Explicit exclusions protect the team during implementation and set honest expectations with stakeholders
User Narratives
Capture user needs using the pattern: "As a [specific persona], I need [capability] because [underlying motivation]"
Guidance for effective narratives:
- Personas should be specific enough to guide design tradeoffs ("billing administrator" rather than "user")
- Describe the desired outcome, not interface mechanics
- The motivation clause must explain what value the user gains
- Account for error scenarios, empty states, and edge conditions
- Represent every distinct persona the feature touches
- Sequence narratives from highest to lowest priority
Sample narratives:
- "As a billing administrator, I need to export invoice history by date range because our finance team requires quarterly reconciliation reports"
- "As a new team member, I need to see a summary of recent project activity because joining mid-project without context slows my contribution"
Characteristics of Strong User Narratives
Apply the INVEST checklist:
- Independent: Deliverable without coupling to other narratives
- Negotiable: Implementation details remain flexible
- Valuable: Produces a tangible benefit for the end user
- Estimable: Engineering can gauge the approximate effort
- Small: Completable within a single iteration
- Testable: Verification criteria are unambiguous
Pitfalls to Avoid in User Narratives
- Vagueness: "As a user, I want better performance" -- specify which operation and what threshold
- Dictating implementation: "As a user, I want a modal dialog" -- describe the need, not the widget
- Missing motivation: "As a user, I want to click save" -- explain the purpose behind the action
- Oversized scope: "As a user, I want full team management" -- decompose into discrete capabilities
- Internal framing: "As the backend team, we want to migrate the database" -- this is a technical task, not a user narrative
Requirement Tiers
Tier Classification
Critical (P0): The initiative is incomplete without these. They represent the minimum threshold for solving the stated problem. Litmus test: "If we remove this, does the core problem remain unsolved?" If yes, it stays at P0.
Important (P1): Materially enhances the experience but the fundamental use case functions without them. These are strong candidates for rapid follow-up after initial release.
Deferred (P2): Intentionally excluded from the first version, but the architecture should accommodate them. Recording these prevents design choices that create future obstacles.
Prioritization Discipline
- Guard P0 ruthlessly. A lean critical set accelerates learning and delivery.
- When every item is labeled critical, no item is truly critical. Challenge each P0: "Would we genuinely delay release for this?"
- P1 items should represent near-certain follow-ups, not speculative wishes.
- P2 items serve as architectural guardrails, shaping design without consuming implementation effort.
The MoSCoW Lens
An alternative classification that maps naturally to stakeholder negotiations:
- Must have: Without these, the release has no value. Non-negotiable.
- Should have: Expected by users and important, but the release remains viable without them.
- Could have: Welcome additions if capacity permits. Omitting them does not delay the timeline.
- Won't have (this cycle): Explicitly deferred. Documenting these eliminates ambiguity.
Measuring Success
Early Signals (Days to Weeks Post-Launch)
Indicators that shift quickly and reveal immediate reception:
- Uptake rate: proportion of eligible users who engage with the new capability
- Activation rate: proportion who complete the primary intended action
- Completion rate: proportion who accomplish their end-to-end goal
- Duration: elapsed time for the core workflow
- Failure rate: frequency of errors, dead ends, or abandoned attempts
- Return frequency: how often users revisit the capability
Sustained Signals (Weeks to Months Post-Launch)
Indicators that mature over time and reflect lasting impact:
- Retention lift: measurable improvement in user retention attributable to the feature
- Revenue contribution: driven upgrades, expansions, or new bookings
- Satisfaction shift: movement in NPS, CSAT, or qualitative sentiment
- Support load reduction: decrease in related support inquiries
- Win-rate influence: improvement in competitive deal outcomes
Establishing Targets
- Targets must be precise: "60% uptake within the first 14 days" rather than "strong adoption"
- Derive targets from analogous launches, industry norms, or stated hypotheses
- Define both a baseline expectation and a stretch aspiration
- Specify the measurement instrument: which tool, which query, which time window
- Schedule evaluation checkpoints: one week, one month, one quarter after launch
Verification Criteria
Express acceptance criteria using structured conditions or checklists.
Structured Conditions:
- Given [starting state or precondition]
- When [user action]
- Then [expected system behavior]
Example:
- Given the organization has enabled single sign-on
- When an employee navigates to the login screen
- Then the system redirects them to the organization's identity provider
Checklist Approach:
Writing Effective Verification Criteria
- Cover the primary path, error conditions, and boundary scenarios
- Describe observable behavior, not internal implementation
- Include negative cases: what should explicitly not occur
- Each criterion should be independently verifiable
- Replace subjective language ("responsive", "intuitive", "seamless") with concrete thresholds
Scope Governance
Indicators of Scope Expansion
Watch for these warning signs:
- Requirements surface after the specification is finalized
- Incremental additions compound into a substantially larger effort
- The team builds capabilities that no user requested ("since we are already in there...")
- Target dates shift without a deliberate re-scoping conversation
- Stakeholders append requirements without corresponding removals
Containment Strategies
- Anchor every specification with explicit exclusions
- Enforce a tradeoff rule: new scope additions require a corresponding removal or timeline adjustment
- Maintain a clear boundary between the current iteration and subsequent phases
- Periodically verify that every requirement traces back to the stated problem
- Apply time caps to exploratory work: "if we cannot resolve X within two days, we defer it"
- Maintain a "future ideas" backlog for worthy suggestions that fall outside the current scope
Unresolved Questions
Every PRD should track open items:
- Record questions that require resolution before or during implementation
- Assign each question to a responsible party: engineering, design, legal, data science, or a specific stakeholder
- Classify questions as blocking (must resolve before work begins) or non-blocking (can resolve in parallel with implementation)
Timing and Sequencing
- Document hard deadlines: contractual obligations, external events, regulatory milestones
- Identify cross-team dependencies and their expected delivery dates
- Recommend phasing if the initiative exceeds a single release cycle
1---
2name: prd-writing
3description: Draft PRDs with problem framing, users, requirements, acceptance criteria, scope, and measurable outcomes.
4metadata:
5 source: https://skillmd.com/skills/vm0-ai/prd-writing
6---
7
8## Document Architecture
9
10Organize every PRD around these core sections. Adapt the depth of each section to the complexity of the initiative.
11
12### The Problem Frame
13
14Ground the entire document in a clearly articulated problem:
15
16- Identify the specific user pain point in concrete, observable terms
17- Quantify who suffers from this problem and at what frequency
18- Articulate the consequences of inaction: lost revenue, user attrition, operational burden, or competitive exposure
19- Anchor claims in evidence drawn from support tickets, user interviews, behavioral data, or market signals
20
21### Desired Outcomes
22
23Translate the problem into 3-5 measurable targets:
24
25- Frame each outcome around observable change: behavior shifts, efficiency gains, error reduction
26- Separate user-facing outcomes (what improves for the customer) from organizational outcomes (what the business gains)
27- Express outcomes as results rather than deliverables: "cut onboarding duration by half" instead of "redesign the onboarding flow"
28- Every outcome must answer: "what evidence will confirm we achieved this?"
29
30### Boundaries and Exclusions
31
32Prevent runaway scope by documenting 3-5 items that are deliberately excluded:
33
34- Name adjacent capabilities that will not be addressed in this iteration
35- Provide a brief rationale for each exclusion: insufficient data, low leverage, better suited to a follow-up phase, or separate workstream
36- Explicit exclusions protect the team during implementation and set honest expectations with stakeholders
37
38### User Narratives
39
40Capture user needs using the pattern: "As a [specific persona], I need [capability] because [underlying motivation]"
41
42Guidance for effective narratives:
43
44- Personas should be specific enough to guide design tradeoffs ("billing administrator" rather than "user")
45- Describe the desired outcome, not interface mechanics
46- The motivation clause must explain what value the user gains
47- Account for error scenarios, empty states, and edge conditions
48- Represent every distinct persona the feature touches
49- Sequence narratives from highest to lowest priority
50
51Sample narratives:
52- "As a billing administrator, I need to export invoice history by date range because our finance team requires quarterly reconciliation reports"
53- "As a new team member, I need to see a summary of recent project activity because joining mid-project without context slows my contribution"
54
55### Characteristics of Strong User Narratives
56
57Apply the INVEST checklist:
58
59- **Independent**: Deliverable without coupling to other narratives
60- **Negotiable**: Implementation details remain flexible
61- **Valuable**: Produces a tangible benefit for the end user
62- **Estimable**: Engineering can gauge the approximate effort
63- **Small**: Completable within a single iteration
64- **Testable**: Verification criteria are unambiguous
65
66### Pitfalls to Avoid in User Narratives
67
68- Vagueness: "As a user, I want better performance" -- specify which operation and what threshold
69- Dictating implementation: "As a user, I want a modal dialog" -- describe the need, not the widget
70- Missing motivation: "As a user, I want to click save" -- explain the purpose behind the action
71- Oversized scope: "As a user, I want full team management" -- decompose into discrete capabilities
72- Internal framing: "As the backend team, we want to migrate the database" -- this is a technical task, not a user narrative
73
74## Requirement Tiers
75
76### Tier Classification
77
78**Critical (P0)**: The initiative is incomplete without these. They represent the minimum threshold for solving the stated problem. Litmus test: "If we remove this, does the core problem remain unsolved?" If yes, it stays at P0.
79
80**Important (P1)**: Materially enhances the experience but the fundamental use case functions without them. These are strong candidates for rapid follow-up after initial release.
81
82**Deferred (P2)**: Intentionally excluded from the first version, but the architecture should accommodate them. Recording these prevents design choices that create future obstacles.
83
84### Prioritization Discipline
85
86- Guard P0 ruthlessly. A lean critical set accelerates learning and delivery.
87- When every item is labeled critical, no item is truly critical. Challenge each P0: "Would we genuinely delay release for this?"
88- P1 items should represent near-certain follow-ups, not speculative wishes.
89- P2 items serve as architectural guardrails, shaping design without consuming implementation effort.
90
91### The MoSCoW Lens
92
93An alternative classification that maps naturally to stakeholder negotiations:
94
95- **Must have**: Without these, the release has no value. Non-negotiable.
96- **Should have**: Expected by users and important, but the release remains viable without them.
97- **Could have**: Welcome additions if capacity permits. Omitting them does not delay the timeline.
98- **Won't have (this cycle)**: Explicitly deferred. Documenting these eliminates ambiguity.
99
100## Measuring Success
101
102### Early Signals (Days to Weeks Post-Launch)
103
104Indicators that shift quickly and reveal immediate reception:
105
106- **Uptake rate**: proportion of eligible users who engage with the new capability
107- **Activation rate**: proportion who complete the primary intended action
108- **Completion rate**: proportion who accomplish their end-to-end goal
109- **Duration**: elapsed time for the core workflow
110- **Failure rate**: frequency of errors, dead ends, or abandoned attempts
111- **Return frequency**: how often users revisit the capability
112
113### Sustained Signals (Weeks to Months Post-Launch)
114
115Indicators that mature over time and reflect lasting impact:
116
117- **Retention lift**: measurable improvement in user retention attributable to the feature
118- **Revenue contribution**: driven upgrades, expansions, or new bookings
119- **Satisfaction shift**: movement in NPS, CSAT, or qualitative sentiment
120- **Support load reduction**: decrease in related support inquiries
121- **Win-rate influence**: improvement in competitive deal outcomes
122
123### Establishing Targets
124
125- Targets must be precise: "60% uptake within the first 14 days" rather than "strong adoption"
126- Derive targets from analogous launches, industry norms, or stated hypotheses
127- Define both a baseline expectation and a stretch aspiration
128- Specify the measurement instrument: which tool, which query, which time window
129- Schedule evaluation checkpoints: one week, one month, one quarter after launch
130
131## Verification Criteria
132
133Express acceptance criteria using structured conditions or checklists.
134
135**Structured Conditions**:
136- Given [starting state or precondition]
137- When [user action]
138- Then [expected system behavior]
139
140Example:
141- Given the organization has enabled single sign-on
142- When an employee navigates to the login screen
143- Then the system redirects them to the organization's identity provider
144
145**Checklist Approach**:
146- [ ] Administrators can configure the identity provider URL in workspace settings
147- [ ] Team members see a branded sign-on option on the login screen
148- [ ] First-time SSO authentication provisions a new account automatically
149- [ ] SSO authentication links to an existing account when the email matches
150- [ ] Authentication failures surface a descriptive error message
151
152### Writing Effective Verification Criteria
153
154- Cover the primary path, error conditions, and boundary scenarios
155- Describe observable behavior, not internal implementation
156- Include negative cases: what should explicitly not occur
157- Each criterion should be independently verifiable
158- Replace subjective language ("responsive", "intuitive", "seamless") with concrete thresholds
159
160## Scope Governance
161
162### Indicators of Scope Expansion
163
164Watch for these warning signs:
165
166- Requirements surface after the specification is finalized
167- Incremental additions compound into a substantially larger effort
168- The team builds capabilities that no user requested ("since we are already in there...")
169- Target dates shift without a deliberate re-scoping conversation
170- Stakeholders append requirements without corresponding removals
171
172### Containment Strategies
173
174- Anchor every specification with explicit exclusions
175- Enforce a tradeoff rule: new scope additions require a corresponding removal or timeline adjustment
176- Maintain a clear boundary between the current iteration and subsequent phases
177- Periodically verify that every requirement traces back to the stated problem
178- Apply time caps to exploratory work: "if we cannot resolve X within two days, we defer it"
179- Maintain a "future ideas" backlog for worthy suggestions that fall outside the current scope
180
181## Unresolved Questions
182
183Every PRD should track open items:
184
185- Record questions that require resolution before or during implementation
186- Assign each question to a responsible party: engineering, design, legal, data science, or a specific stakeholder
187- Classify questions as blocking (must resolve before work begins) or non-blocking (can resolve in parallel with implementation)
188
189## Timing and Sequencing
190
191- Document hard deadlines: contractual obligations, external events, regulatory milestones
192- Identify cross-team dependencies and their expected delivery dates
193- Recommend phasing if the initiative exceeds a single release cycle