write-prd ยท diff
git:20260303.f77c189 to git:20260303.19bc151
61 added, 48 removed. Audit A to A.
---
name: write-prd
description: >
Write a Product Requirements Document (PRD). Use when the user says "write a PRD",
"document this feature", "product requirements for X", "write requirements",
- "I need a PRD", or wants to formalize a feature or product idea into a structured doc
- - even if they don't explicitly say "PRD".
+ "I need a PRD", "pitch this feature", or wants to formalize a feature or product
+ idea into a structured doc - even if they don't explicitly say "PRD".
---
## Overview
- A PRD defines the problem, the solution, and the success criteria. It is the contract between product and engineering. A good PRD eliminates ambiguity before it becomes a bug.
+ Based on **Shape Up** by Ryan Singer (Basecamp). A PRD defines the problem, the appetite, and the solution boundaries - not a detailed spec. The key insight from Shape Up: fix the time, flex the scope. Define how much the team is willing to spend before deciding what to build.
## Workflow
- ### Step 1: Clarify scope
- If the user hasn't provided enough context, ask:
- - What problem does this solve for the user?
- - Who is the target user?
- - What's the MVP scope vs. future iterations?
+ ### Step 1: Set the Appetite
+ Before writing requirements, define the appetite - how much time is this worth?
+ - **Small batch:** 1-2 weeks
+ - **Big batch:** 4-6 weeks
- ### Step 2: Write the PRD header
+ If the solution requires more time than the appetite allows, cut the scope - don't extend the time.
+
+ ### Step 2: Write the Problem Statement
+ One paragraph. Answer: what is broken or missing today, who is affected, and what is the cost of not solving it. Avoid mentioning solutions here.
+
+ ### Step 3: Write the Pitch (Shape Up format)
+ Structure:
```
# PRD: [Feature Name]
- **Author:** [your name]
+ **Appetite:** [Small batch / Big batch]
**Status:** Draft
- **Last Updated:** [date]
- **Stakeholders:** [your team]
- ```
+ **Author:** [your name]
- ### Step 3: Write the Problem Statement
- One paragraph. Answer: what is broken or missing today, who is affected, and what is the cost of not solving it.
+ ## Problem
+ [What's broken, who's affected, cost of inaction]
- ### Step 4: Define Goals and Non-Goals
- **Goals:** 2-4 bullet points of what success looks like.
- **Non-Goals:** Explicit list of what this PRD does NOT cover. Non-goals prevent scope creep.
+ ## Solution
+ [Fat marker sketch - broad strokes, not pixel-perfect]
- ### Step 5: Define Success Metrics
- Quantify success. Examples:
- - "Reduce support tickets related to X by 30%"
- - "90% of users complete onboarding in under 5 minutes"
- - "Feature adopted by 60% of active users within 30 days"
+ ## Rabbit Holes
+ [Specific technical or design traps to avoid]
- ### Step 6: Write Functional Requirements
- Number each requirement. Use "The system shall..." or "Users can..." format.
- Group by user flow or component.
+ ## No-Gos
+ [Explicitly what this does NOT include]
+ ```
- ### Step 7: Write Open Questions
- List unresolved decisions with owners and due dates. Unresolved questions become blockers - surface them early.
+ ### Step 4: Write the Solution at the right altitude
+ Shape Up's "fat marker sketch" principle: describe the solution broadly enough that engineers have room to make decisions. Over-specifying kills ownership and slows delivery.
- ### Step 8: Add Appendix (optional)
- Link to mocks, research, analytics, or related tickets.
+ Write requirements at the level of: "Users can do X" - not "There is a button in the top-right corner."
+ ### Step 5: Define Rabbit Holes
+ List specific traps the team could fall into. Examples:
+ - "Don't rebuild the notification system - use existing infrastructure"
+ - "Don't support bulk operations in v1"
+
+ ### Step 6: Define No-Gos
+ Explicit list of what this does NOT cover. This is the most important section for scope control.
+
+ ### Step 7: Add Open Questions
+ Format:
+ ```
+ Q: [question]
+ Owner: [name]
+ Due: [date]
+ ```
+
## Anti-Patterns
- **1. Solutioning in the problem statement**
+ **1. Specifying solutions in the problem statement**
Bad: "We need to add a modal because users don't see the CTA."
- Good: "30% of users drop off at the checkout step. Research suggests the CTA is not visible enough."
+ Good: "30% of users drop off at checkout. The CTA is not visible enough."
- **2. Vague requirements**
- Bad: "The system should be fast."
- Good: "Page load time should be under 2 seconds for 95th percentile users on 4G."
+ **2. No appetite defined**
+ Bad: PRD with requirements but no time boundary.
+ Good: "This is a small batch - 2 weeks max. If the solution needs more, cut scope."
- **3. No non-goals**
- Bad: PRD with only goals listed.
- Good: Explicit "Out of Scope" section that prevents engineering from over-building.
+ **3. Missing No-Gos**
+ Bad: PRD with only what's included.
+ Good: Explicit No-Gos that prevent scope creep during build.
- **4. Missing success metrics**
- Bad: "The feature is successful when users like it."
- Good: Quantified metric tied to a business or user outcome.
+ **4. Over-specified requirements**
+ Bad: "The button is blue, 48px, positioned top-right with 16px margin."
+ Good: "Users can trigger X from the main action area." (Let design decide the details.)
## Quality Checklist
- - [ ] Problem statement explains the "why", not the "what"
- - [ ] Goals are outcome-based, not output-based
- - [ ] Non-goals are explicit
- - [ ] Success metrics are measurable and time-bound
- - [ ] Each functional requirement is unambiguous
- - [ ] Open questions have owners
- - [ ] PRD is readable by an engineer with no prior context
+ - [ ] Appetite is defined (small or big batch)
+ - [ ] Problem statement explains "why", not "what"
+ - [ ] Solution is at the right altitude - no pixel-level specs
+ - [ ] Rabbit holes are listed
+ - [ ] No-Gos are explicit
+ - [ ] Open questions have owners and due dates