prd-writing

## 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