SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsprd-writing-guide

prd-writing-guide

Writing & research

View repository

Updated 10-16 02:36

About this skill

PRD Writing Guide

Overview

Write PRDs so complete that development teams can implement the entire product without asking a single clarifying question.

Skill Workflow Context

This skill is part of a 3-skill pipeline:

┌─────────────────┐     ┌─────────────────┐     ┌─────────────────┐
│ prd-writing-    │────►│ prd-to-         │     │ reverse-        │
│ guide           │     │ engineering-    │     │ engineering-    │
│                 │     │ spec            │     │ spec            │
│ [THIS SKILL]    │     │ PRD→Eng Spec   │     │ Code→Spec       │
└─────────────────┘     └─────────────────┘     └─────────────────┘

For AI Agent products, use ai-agent-prd instead (which extends this skill).


**Handoff contract:** The PRD this skill produces must be complete enough to pass `prd-to-engineering-spec`'s Phase 0 validation without any ❌ items.

### The PRD Quality Test

┌─────────────────────────────────────────────────────────────────┐ │ The Developer Test │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ Give your PRD to a developer who knows nothing about the │ │ project. Can they: │ │ │ │ □ Understand WHY we're building this? │ │ □ Know exactly WHAT to build (and what NOT to)? │ │ □ Handle EVERY edge case without guessing? │ │ □ Write test cases for EVERY requirement? │ │ □ Estimate the work with confidence? │ │ │ │ If any answer is "no", your PRD is incomplete. │ │ │ └─────────────────────────────────────────────────────────────────┘


## Core Principle: Eliminate Ambiguity

**Every sentence in a PRD should have exactly one interpretation.**

| Ambiguous (❌) | Precise (✅) |
|----------------|--------------|
| "Fast response time" | "API response < 200ms at P95" |
| "User-friendly interface" | "New users complete task in < 2 minutes without help" |
| "Handle errors gracefully" | "Show error toast with retry button; log to monitoring" |
| "Support large datasets" | "Handle up to 1M records with < 3s query time" |
| "Secure authentication" | "OAuth 2.0 with JWT, 24h token expiry, refresh tokens" |

## Quick Start

1. Use the [Discovery Questions](#phase-1-requirement-discovery) to gather requirements
2. Structure with the [PRD Template](references/prd-template.md)
3. Apply the [Seven Lenses](#the-seven-lenses) to each requirement
4. Validate with the [Completeness Checklist](references/completeness-checklist.md)
5. Verify with the [Developer Handoff Checklist](#developer-handoff-checklist)

### Sensitive Information & Confidentiality (Required)

PRDs often contain information that should **not** leak outside your organization.

- **Do not** paste secrets (API keys, tokens, passwords), customer PII, private endpoints, internal credentials, or confidential incident details into the PRD.
- Use **placeholders** instead (e.g., `OPENAI_API_KEY`, `[INTERNAL_URL]`, `[CUSTOMER_ID]`) and keep the real values in your secret manager / internal docs.
- Before sharing a PRD externally (vendors, community, public issues), do a quick **redaction pass**:
  - Replace internal URLs, private repo links, Jira/Linear IDs (if sensitive), and customer names.
  - Remove exact budgets/cost ceilings if they are confidential (or mark them as ranges).

### Product Type Emphasis

Different products require different PRD emphasis. Adjust depth accordingly:

| Product Type | Emphasize | De-emphasize |
|-------------|-----------|--------------|
| **Mobile/Web App** | UX flows, states, responsive design, accessibility | Infrastructure details |
| **API Service** | Interface contracts, data schemas, error codes, rate limits | UI/UX flows |
| **Data Pipeline** | Data flow diagrams, transformation rules, quality checks, SLAs | User interaction |
| **B2B SaaS** | Multi-tenancy, permissions, billing, onboarding | Consumer UX patterns |
| **AI-Powered Product** | See [ai-features-prd.md](references/ai-features-prd.md); for Agents use `ai-agent-prd` | N/A |
| **Internal Tool** | Workflow efficiency, integration with existing systems | Scalability, marketing |

---

## Workflow Overview

Phase 1: Discovery ────► Understand the problem space ↓ Phase 2: Structure ────► Organize requirements systematically ↓ Phase 3: Detail ───────► Fill in every edge case ↓ Phase 4: Validate ─────► Check completeness ↓ Phase 5: Review ───────► Confirm with stakeholders & dev


---

## Phase 1: Requirement Discovery

**Goal:** Ask the right questions to uncover all requirements.

### The Discovery Framework

For every feature, systematically explore these dimensions:

#### 1. Problem Space
- What problem are we solving?
- Who has this problem? How severe is it?
- How do they solve it today? What's painful?
- Why solve it now? What's the business driver?
- How will we know we've solved it? (Metrics)

#### 2. User Space
- Who are ALL the users? (Don't forget admins, support, etc.)
- What are their goals? Motivations?
- What's their technical proficiency?
- What context are they in? (Mobile? Rushed? Multitasking?)
- How often will they use this?

#### 3. Functional Space
- What must the system DO?
- What must it NOT do? (Explicit scope boundaries)
- What's the MVP vs. nice-to-have?
- What's the complete happy path?
- What's every unhappy path?

#### 4. Data Space
- What data is needed?
- Where does it come from?
- How is it created, updated, deleted?
- How long must it be retained?
- Who can see/modify it?

#### 5. Integration Space
- What systems does this connect to?
- What data is exchanged?
- What if those systems are unavailable?
- Who owns those systems?

#### 6. Constraint Space
- What are the performance requirements?
- What are the security requirements?
- What are the compliance requirements?
- What are the budget/timeline constraints?
- What existing systems/tech must we use?

### Discovery Questions Template

See [discovery-questions.md](references/discovery-questions.md) for a comprehensive question bank organized by domain.

---

## Phase 2: Requirement Structure

**Goal:** Organize discovered requirements into a navigable, complete document.

### PRD Structure

  1. Executive Summary

    • One-paragraph problem statement
    • One-paragraph solution overview
    • Success metrics (3-5 key KPIs)

  2. Background & Context

    • Business context
    • User research summary
    • Current state analysis
    • Competitive landscape (if relevant)

  3. Goals & Non-Goals

    • What we're trying to achieve
    • What we're explicitly NOT doing
    • Success criteria

  4. User Stories & Requirements

    • User personas
    • User stories with acceptance criteria
    • Functional requirements
    • Business rules

  5. User Experience

    • User flows
    • Wireframes/mockups
    • Interaction specifications
    • Error states and messaging

  6. Data Requirements

    • Data model (conceptual)
    • Data sources
    • Data lifecycle

  7. Non-Functional Requirements

    • Performance
    • Security
    • Scalability
    • Accessibility

  8. Dependencies & Integrations

    • System dependencies
    • External integrations
    • Team dependencies

  9. Timeline & Milestones

    • Phases
    • Key milestones
    • Release criteria

  10. Risks & Open Questions

    • Known risks
    • Assumptions
    • Unresolved questions

Appendix - Glossary - Reference documents - Revision history


See [prd-template.md](references/prd-template.md) for the complete template with examples.

---

## Phase 3: Requirement Detail

**Goal:** Make every requirement implementable without guesswork.

### The Seven Lenses

Apply these seven lenses to EVERY requirement to ensure completeness:

┌──────────────────────────────────────────────────────────────────┐ │ The Seven Lenses │ ├──────────────────────────────────────────────────────────────────┤ │ │ │ 1. HAPPY PATH: What happens when everything works? │ │ │ │ 2. SAD PATHS: What can go wrong? How do we handle each? │ │ │ │ 3. EDGE CASES: What are the boundary conditions? │ │ │ │ 4. PERMISSIONS: Who can do this? Who can't? │ │ │ │ 5. STATE: What states exist? How do they transition? │ │ │ │ 6. DATA: What data flows in/out? Validation? Persistence? │ │ │ │ 7. FEEDBACK: What does the user see/hear at each step? │ │ │ └──────────────────────────────────────────────────────────────────┘


### Lens 1: Happy Path

Document the complete successful flow:
- Entry point: How does the user start?
- Each step: What exactly happens?
- Exit point: How does it end?
- Result: What's the outcome?

### Lens 2: Sad Paths

For every step, ask "what if it fails?":

| Failure Type | Questions to Answer |
|--------------|---------------------|
| **User Error** | Invalid input → What message? Can they retry? |
| **System Error** | Server fails → What message? Data preserved? |
| **External Failure** | Integration down → Fallback? Retry? Queue? |
| **Timeout** | Operation takes too long → Cancel? Retry? |
| **Concurrency** | Two users edit same thing → Who wins? Conflict resolution? |

### Lens 3: Edge Cases

| Category | Examples |
|----------|----------|
| **Empty** | Zero items, blank input, no data yet |
| **One** | Single item (different from multiple) |
| **Many** | Maximum items, pagination needed |
| **Boundary** | Min/max values, exactly at threshold |
| **Invalid** | Wrong type, out of range, special characters |
| **Timing** | Midnight, timezone boundaries, DST transitions |

### Lens 4: Permissions

For every action, define:

| Question | Example Answer |
|----------|----------------|
| Who can perform this? | Admin, Owner, Member |
| Who cannot? | Guest, Suspended users |
| What if unauthorized? | 403 page with "request access" button |
| How are permissions assigned? | Owner grants via settings page |
| Can permissions be revoked? | Yes, immediate effect |

### Lens 5: State

For entities with state, document:

State Machine Example:

┌───────┐ submit ┌─────────┐ approve ┌──────────┐ │ Draft │─────────────►│ Pending │──────────────►│ Approved │ └───────┘ └─────────┘ └──────────┘ ▲ │ │ reject │ └───────────────────────┘

Transitions:

  • Draft → Pending: Author submits. Requires: all fields filled.
  • Pending → Approved: Admin approves. Side effect: notify author.
  • Pending → Draft: Admin rejects. Requires: reason. Notify author.

Who can trigger:

  • Submit: Author only
  • Approve/Reject: Admin only

### Lens 6: Data

For every piece of data:

| Attribute | Specify |
|-----------|---------|
| **Source** | Where does it come from? |
| **Type** | String, number, date, enum, etc. |
| **Format** | Regex pattern, max length, allowed values |
| **Required** | Is it optional? Conditionally required? |
| **Default** | If not provided, what value? |
| **Validation** | What makes it valid/invalid? |
| **Display** | How is it shown to users? |
| **Storage** | How long kept? Where stored? |

### Lens 7: Feedback

At every step, what does the user experience?

| Step | Visual Feedback | Audio/Haptic | Message |
|------|-----------------|--------------|---------|
| Loading | Spinner on button | None | None |
| Success | Green checkmark | Success chime | "Saved successfully" |
| Error | Red highlight | Error vibration | "Email format invalid" |
| Warning | Yellow banner | None | "Unsaved changes will be lost" |

---

## Phase 4: Validation

**Goal:** Verify PRD completeness before handoff.

### Completeness Checklist

Use [completeness-checklist.md](references/completeness-checklist.md) to verify every section.

### Self-Review Questions

Before sharing the PRD, ask yourself:

1. **The Stranger Test**: Could someone who knows nothing about this project implement it?

2. **The Negative Test**: Have I defined what we're NOT doing?

3. **The Edge Case Test**: Have I thought about empty, one, many, and error states?

4. **The Permission Test**: Have I defined who can do what?

5. **The State Test**: Have I mapped all states and transitions?

6. **The Failure Test**: Have I documented what happens when things go wrong?

7. **The Metric Test**: Have I defined how we'll measure success?

8. **The Test Case Test**: Could QA write test cases from this?

---

## Phase 5: Review

**Goal:** Confirm understanding with stakeholders and development team.

### Stakeholder Review

Confirm with product/business stakeholders:
- [ ] Problem statement accurate?
- [ ] Success metrics agreed?
- [ ] Scope and non-scope correct?
- [ ] Priority order correct?
- [ ] Timeline realistic?

### Engineering Review

Walk through with development team:
- [ ] Requirements understood?
- [ ] Questions answered?
- [ ] Technical feasibility confirmed?
- [ ] Effort estimate possible?
- [ ] Dependencies identified?
- [ ] Risks surfaced?

### The Question Log

Track every question asked during reviews:

| Question | Asker | Answer | Added to PRD? |
|----------|-------|--------|---------------|
| "What if user has no email?" | Dev | "Email required for signup" | ✓ Section 4.2 |

**Every question reveals a gap.** Update the PRD with the answer.

---

## Developer Handoff Checklist

Before declaring PRD "ready for development":

### Content Completeness
- [ ] Every user story has acceptance criteria
- [ ] Every acceptance criterion is testable
- [ ] All business rules documented with examples
- [ ] All edge cases documented
- [ ] All error handling specified
- [ ] All states and transitions mapped
- [ ] All permissions defined
- [ ] All data fields specified with validation

### Clarity
- [ ] No ambiguous terms (search for: appropriate, reasonable, etc.)
- [ ] No missing boundaries (search for: large, many, some)
- [ ] No undefined references (every term in glossary or explained)

### Testability
- [ ] QA can write test cases for every requirement
- [ ] Success criteria are measurable
- [ ] Non-functional requirements are quantified

### Alignment
- [ ] Stakeholders have approved
- [ ] Engineering has reviewed
- [ ] Questions have been answered and documented

---

## Common Pitfalls

See [common-pitfalls.md](references/common-pitfalls.md) for detailed guidance on avoiding these mistakes:

### Pitfall 1: Solution Disguised as Problem
❌ "We need a dashboard"
✅ "Users can't see their key metrics at a glance. They currently export to Excel and manually calculate."

### Pitfall 2: Vague Acceptance Criteria
❌ "User can easily create an account"
✅ "User completes signup in < 60 seconds with only email and password"

### Pitfall 3: Missing Negative Cases
❌ "User can upload a file"
✅ "User can upload a file (max 10MB, types: PDF/DOC/DOCX). On invalid type: show error and list allowed types. On size exceeded: show error with current and max size."

### Pitfall 4: Implicit Assumptions
❌ "Display user's orders"
✅ "Display user's orders (sorted by date descending, paginated at 20 per page, show last 90 days by default)"

### Pitfall 5: Missing State Handling
❌ "Order can be cancelled"
✅ "Order can be cancelled by customer if status is Pending or Confirmed. Shipped orders cannot be cancelled (show 'Contact support'). Cancellation triggers: refund, inventory restore, email notification."

---

## AI Feature Requirements

If your product includes AI features, see [ai-features-prd.md](references/ai-features-prd.md) for additional requirements:

- Behavioral specification (what the AI should do)
- Quality metrics (accuracy, relevance, etc.)
- Failure handling (what if AI fails or produces bad output?)
- User expectations (how to set appropriate expectations)
- Feedback mechanisms (how users report issues)
- Cost considerations (if applicable)

---

## Resources

**Scripts:**
- `scripts/generate_prd_skeleton.sh` - Generate PRD document structure

**References:**
- `references/prd-template.md` - Complete PRD template with examples
- `references/discovery-questions.md` - Comprehensive question bank
- `references/completeness-checklist.md` - Validation checklist
- `references/common-pitfalls.md` - Mistakes to avoid
- `references/ai-features-prd.md` - AI feature requirements guide
- `references/writing-style-guide.md` - How to write clear requirements
- `references/prioritization-management.md` - Priority frameworks, change management, compliance
- `references/worked-example.md` - **End-to-end worked example** (HelpBot customer support agent)

---

## Summary: The PRD Writer's Mindset

┌─────────────────────────────────────────────────────────────────┐ │ 1. ASSUME NOTHING - If not written, it doesn't exist. │ │ 2. BE SPECIFIC - Numbers, not adjectives. │ │ 3. THINK NEGATIVELY - What can go wrong? │ │ 4. SEEK CHALLENGES - Questions reveal gaps. │ │ 5. ITERATE - PRDs are never done on first draft. │ └─────────────────────────────────────────────────────────────────┘


The goal is to **transfer understanding** so completely that anyone can build exactly what you envision.