Okwinds Miscellany Prd Writing Guide

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.

Quick Start

1. Use the Discovery Questions to gather requirements
2. Structure with the PRD Template
3. Apply the Seven Lenses to each requirement
4. Validate with the Completeness Checklist
5. Verify with the 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:

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 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 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?":

Lens 3: Edge Cases

Lens 4: Permissions

For every action, define:

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:

Lens 7: Feedback

At every step, what does the user experience?

Phase 4: Validation

Goal: Verify PRD completeness before handoff.

Completeness Checklist

Use 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:

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

Converted and distributed by TomeVault — claim your Tome and manage your conversions.