prd-writing

Imported from okou-ai/vm0-skills (prd-writing/SKILL.md). Install upstream with npx skills add okou-ai/vm0-skills --skill prd-writing. Copyright stays with the author.

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:

• Administrators can configure the identity provider URL in workspace settings
• Team members see a branded sign-on option on the login screen
• First-time SSO authentication provisions a new account automatically
• SSO authentication links to an existing account when the email matches
• Authentication failures surface a descriptive error message

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