PRD Writing

Purpose

Creates lightweight, actionable Product Requirements Documents that bridge product and engineering, focusing on user value rather than implementation details.

When NOT to Use This Skill

• Technical implementation planning (use sparc-planning instead)
• API documentation (use api-doc-writer instead)
• Bug fixes or minor enhancements (no PRD needed)
• Already have detailed PRD, need review (use prd-reviewing instead)
• Single feature detail with edge cases (use feature-spec-writing instead)

Workflow

Step 1: Context Gathering

Invoke check-history to understand project context, then ask clarifying questions:

Questions to ask:

1. What problem are we solving? (Focus on user pain, not solution)
2. Who experiences this problem? (Target users/personas)
3. What's the business impact? (Revenue, retention, efficiency)
4. What constraints exist? (Timeline, technology, resources)
5. What's already been tried? (Previous solutions, why they failed)

Step 2: Problem Definition

Define the user problem clearly. Focus on the problem, not the solution.

Good problem statement:

Users abandon checkout when shipping costs are unclear,
resulting in 23% cart abandonment rate.

Bad problem statement:

We need to add a shipping calculator widget.
(This is a solution, not a problem)

Step 3: User Stories Creation

Write user stories following the standard format and INVEST criteria:

**Format:**
As a [user type], I want [goal], so that [benefit]

**INVEST Criteria:**

- Independent: Can be delivered separately
- Negotiable: Details can be discussed
- Valuable: Delivers user value
- Estimable: Can be sized by engineering
- Small: Fits in a sprint (or can be split)
- Testable: Has clear acceptance criteria

Example:

As a **shopper**,
I want **to see shipping costs before checkout**,
so that **I can make an informed purchase decision**.

Step 4: Acceptance Criteria Definition

Define "done" for each user story using Given/When/Then format:

Given I am on the product page
And I have entered my shipping address
When I click "Calculate Shipping"
Then I see the shipping cost within 2 seconds
And I see the estimated delivery date
And I can proceed to checkout with the selected option

Include edge cases:

• What happens if address is invalid?
• What if shipping is unavailable to that location?
• What about free shipping thresholds?

Step 5: Scope Definition

Explicitly define scope boundaries:

## In Scope

- Real-time shipping cost calculation on product page
- Integration with 3 carriers (UPS, FedEx, USPS)
- Address validation before calculation

## Out of Scope (v1)

- International shipping (future consideration)
- Shipping insurance options (nice to have)
- Multiple package calculations (complexity)

## Dependencies

- Carrier API integrations (external)
- Address validation service (internal)
- Cart service updates (internal)

## Assumptions

- Carriers provide real-time API access
- 95% of orders are domestic
- Users have valid US addresses

## Open Questions

- [ ] Should we cache shipping rates? For how long?
- [ ] What's the fallback if carrier API is down?

Step 6: Success Metrics

Define measurable success criteria with leading and lagging indicators:

## Key Results

| Metric                     | Current  | Target    | Measurement |
| -------------------------- | -------- | --------- | ----------- |
| Cart abandonment           | 23%      | 18%       | Analytics   |
| Shipping page views        | 0        | 50K/month | Analytics   |
| Support tickets (shipping) | 200/week | 100/week  | Zendesk     |

## Leading Indicators (measure early)

- Shipping calculator usage rate
- Address validation success rate
- Time to calculate shipping

## Guardrails (don't break these)

- Page load time < 3s
- Checkout conversion rate >= current
- Error rate < 1%

Step 7: Output Generation

Generate the PRD using the template in TEMPLATE.md. Ensure:

• Problem is clearly defined (user-focused, not solution-focused)
• User stories follow format and INVEST criteria
• Acceptance criteria are testable and unambiguous
• Scope has explicit in/out boundaries
• Success metrics are measurable
• Open questions are documented
• Stakeholders are identified

Examples

Example 1: E-Commerce - Shipping Calculator

Input: "Users are abandoning checkout because they don't know shipping costs"

Problem Statement:

Users abandon checkout when shipping costs are unclear, resulting in
23% cart abandonment at the shipping step. User research shows 67%
want to see costs before reaching checkout.

User Stories:

US-1: As a shopper, I want to see shipping costs on the product page,
      so that I know total cost before adding to cart.

US-2: As a shopper, I want to compare shipping options,
      so that I can choose between speed and cost.

US-3: As a shopper, I want to save my shipping preference,
      so that I don't have to select it every time.

Acceptance Criteria (US-1):

Given I am on a product page
And I enter my zip code
When I click "Calculate Shipping"
Then I see shipping options within 2 seconds
And each option shows carrier, price, and delivery estimate

---

Example 2: SaaS - Team Permissions

Input: "Admins need to control what team members can access"

Problem Statement:

Organizations cannot control access granularly, forcing all-or-nothing
permissions. This blocks enterprise sales where security compliance
requires role-based access. 15 deals ($2.4M) blocked by this gap.

User Stories:

US-1: As an admin, I want to create custom roles,
      so that I can match our organization's structure.

US-2: As an admin, I want to assign users to roles,
      so that they have appropriate access.

US-3: As an admin, I want to audit role changes,
      so that I can demonstrate compliance.

Scope:

In Scope:
- Role creation with granular permissions
- User-to-role assignment
- Audit log of permission changes

Out of Scope:
- Attribute-based access control (ABAC)
- External identity provider integration
- Permission inheritance across teams

---

Example 3: Fintech - Transaction Alerts

Input: "Users want to know immediately when money moves"

Problem Statement:

Users discover unauthorized transactions too late, averaging 3 days
to notice fraudulent charges. Real-time alerts could reduce fraud
losses by 40% based on industry benchmarks.

User Stories:

US-1: As a cardholder, I want instant notifications for transactions,
      so that I can spot fraud immediately.

US-2: As a cardholder, I want to set spending thresholds,
      so that I'm only alerted for significant transactions.

US-3: As a cardholder, I want to dispute directly from alerts,
      so that I can act quickly on suspicious activity.

Success Metrics:

| Metric | Current | Target |
|--------|---------|--------|
| Time to fraud detection | 3 days | < 1 hour |
| Fraud loss per incident | $450 | $200 |
| User alert engagement | N/A | 80% open rate |

Anti-Patterns to Avoid

Solution-First Thinking

❌ "We need to build a widget that shows shipping"
✅ "Users abandon checkout when shipping costs are unclear"

Epic-Sized Stories

❌ "As a user, I want a complete shipping experience"
✅ "As a user, I want to see shipping costs before checkout"

Vague Acceptance Criteria

❌ "Shipping should be fast"
✅ "Shipping calculation completes within 2 seconds (p95)"

Missing Scope Boundaries

❌ [No out-of-scope section]
✅ "Out of Scope: International shipping, insurance options"

Vanity Metrics

❌ "Increase page views"
✅ "Reduce cart abandonment from 23% to 18%"

Integration with Other Skills

Invokes:

• check-history - Gather project context before writing

Works With:

• prd-reviewing - Review and validate completed PRDs
• feature-spec-writing - Break PRD into detailed feature specs

Followed By:

• prd-implementation-planning - Map PRD to skills and create task list
• sparc-planning - Create technical implementation plan (for complex tasks)
• technical-spec-writing - Design system architecture

Output Validation

Before finalizing the PRD:

• Problem statement focuses on user pain, not solution
• All user stories follow As a/I want/So that format
• Each story has testable acceptance criteria
• Scope explicitly states what's in AND out
• Success metrics are measurable with current/target
• Open questions are documented
• Stakeholders identified for approval

Resources

• See TEMPLATE.md for the complete PRD output format
• See REFERENCE.md for detailed guidance and examples

---

Related Agent

For comprehensive specification guidance that coordinates this and other spec skills, use the specification-architect agent.