PRD Generator Skill Skill

PRD Generator Skill

Overview

Generate structured Product Requirements Documents (PRDs) using problem-first, hypothesis-driven methodology. Ensures clear problem statements, evidence-backed decisions, and traceable implementation phases.

Core principle: Validate "why" before "how". Problem → Evidence → Hypothesis → Solution.

When to Use

Always:

New features requiring product definition
Product changes requiring stakeholder alignment
Requirements gathering for HIGH/EPIC complexity features
Feature requests needing structured analysis

Use specifically for:

Features with unclear requirements (progressive disclosure)
Multi-phase implementations needing tracking
Features requiring decision documentation
Product initiatives needing success metrics

Don't use for:

Simple bug fixes (no PRD needed)
Trivial configuration changes
Code-only refactors without product impact

Purpose

Problem-First: Define problem with evidence before proposing solutions
Hypothesis-Driven: State measurable hypothesis for validation
MoSCoW Prioritization: Prevent scope creep with Must/Should/Could/Won't
Implementation Phases: Track progress with phases table (Status, Dependencies, Plan Links)
Decision Log: Record "why we chose X over Y" for future reference
Traceability: PRD → Planner → Developer with full context

Workflow

Step 1: Gather Requirements

Interactive Mode (when requirements unclear):

// Use AskUserQuestion for structured gathering
const problem = await AskUserQuestion({
  question: 'What problem does this solve? (Be specific about user pain points)',
});

const evidence = await AskUserQuestion({
  question: 'What evidence shows this problem exists? (Data, feedback, metrics)',
});

const hypothesis = await AskUserQuestion({
  question: 'What measurable outcome will prove this feature solves the problem?',
});

Prompt Mode (when requirements provided):

Extract requirements from user prompt or task description

Progressive Disclosure (for ambiguous features):

If requirements are unclear, use 8-phase questioning workflow:

Initiate: Clarify feature goal and scope
Foundation: Understand problem context
Grounding (Market): Research similar solutions
Deep Dive: Explore capabilities and user flows
Grounding (Technical): Assess feasibility
Decisions: Document choices and trade-offs
Generate: Create PRD from gathered context

When to use Progressive Disclosure:

HIGH/EPIC complexity features
Ambiguous user requests ("make it better")
New product areas without existing patterns
Features requiring stakeholder alignment

When to skip:

Clear requirements provided
Similar features already built
Small scope changes

Step 2: Load Template

// Read PRD template
const template = Read({ file_path: '.claude/templates/prd-template.md' });

Template includes these sections (required):

Problem Statement
Evidence
Key Hypothesis
What We're NOT Building (scope exclusions)
Success Metrics table
Core Capabilities (MoSCoW)
Users & Context
Solution Detail (MVP Scope, User Flow)
Technical Approach
Implementation Phases table
Decisions Log table
Research Summary
Risks table
Open Questions

Step 3: Fill Template Sections

Problem Statement (Evidence-Backed):

## Problem Statement

[Specific problem description with user impact]

## Evidence

- User feedback: [quotes or summary]
- Data: [metrics showing problem scale]
- Business impact: [why this matters now]

Key Hypothesis:

## Key Hypothesis

We believe [capability] will [solve problem] for [users].
We'll know we're right when [measurable outcome].

Example:
We believe adding JWT refresh tokens will reduce user re-authentication friction for mobile users.
We'll know we're right when session timeout complaints drop by 50% and mobile DAU increases by 10%.

Success Metrics:

| Metric | Target | How Measured | | -------------------------- | ------ | ----------------------- | | Session timeout complaints | -50% | Support ticket analysis | | Mobile DAU | +10% | Analytics dashboard | | Token refresh success rate | >95% | Backend logs |

Core Capabilities (MoSCoW):

| Priority | Capability | Rationale | | -------- | -------------------------- | -------------------------------------------- | | Must | JWT refresh token endpoint | Required for MVP - enables session extension | | Must | Token rotation on refresh | Security best practice | | Should | Refresh token revocation | Allows user logout from all devices | | Could | Token usage analytics | Nice to have for monitoring | | Won't | Biometric auth integration | Out of scope - future consideration |

MoSCoW Definitions:

Must: MVP blocker - without this, feature fails
Should: High value, include if time permits
Could: Nice to have, defer if needed
Won't: Explicitly excluded from current scope

Users & Context:

## Users & Context

**Primary User**: Mobile app user (iOS/Android) who experiences session expiration mid-workflow

**Current Behavior**: User logs in → session expires after 1 hour → forced to re-login → loses context

**Trigger**: Session expiration during active use

**Success State**: User stays logged in seamlessly, only re-authenticates when truly needed

**Job to Be Done**: When my session expires, I want to continue my work without re-entering credentials, so I can maintain my workflow momentum.

Implementation Phases Table:

| # | Phase | Description | Status | Parallel | Depends | Plan Link | | --- | ------------- | ------------------------------------------------ | ------- | -------- | ------- | --------- | | 1 | Design | Auth architecture design with refresh token flow | pending | No | - | - | | 2 | Backend API | Implement /refresh endpoint with token rotation | pending | No | 1 | - | | 3 | Mobile Client | Add refresh logic to mobile SDK | pending | No | 2 | - | | 4 | Testing | E2E tests for refresh flows | pending | Yes | 2,3 | - | | 5 | Monitoring | Add refresh metrics to dashboard | pending | Yes | 2 | - |

Phase Columns Explained:

#: Phase number
Phase: Short phase name
Description: What gets built in this phase
Status: pending | in_progress | completed | blocked
Parallel: Can this run in parallel with other phases?
Depends: Which phase(s) must complete first? (comma-separated numbers)
Plan Link: Link to planner's implementation plan (.claude/context/plans/impl-{phase}-{date}.md)

Decisions Log:

| Decision | Choice | Alternatives | Rationale | | ---------------- | ---------------------------------- | ------------------------------ | ------------------------------------------- | | Token storage | Secure storage (Keychain/KeyStore) | Local storage, Session storage | Security requirement - tokens are sensitive | | Refresh strategy | Automatic on 401 | Manual user action | Better UX - transparent to user | | Token lifetime | Access: 1hr, Refresh: 30 days | Access: 5min, Refresh: 90 days | Balance security and UX |

Research Summary:

## Research Summary

**Market Context:**

- Auth0, Firebase use similar refresh token patterns
- Industry standard: short-lived access + long-lived refresh
- OWASP recommends token rotation on refresh

**Technical Context:**

- Existing JWT library supports refresh
- Mobile SDK has secure storage
- Backend already has session management

Risks:

| Risk | Likelihood | Mitigation | | ---------------------------- | ---------- | ---------------------------------------- | | Token theft | Medium | Use secure storage, rotate on refresh | | Refresh loop (invalid token) | Low | Add exponential backoff, max retry limit | | Clock skew issues | Low | Use 5min grace period for exp validation |

Open Questions:

## Open Questions

- [ ] What happens to active refresh tokens on password change?
- [ ] How do we handle token refresh during network outage?
- [ ] Should we notify user on refresh token expiration?

Step 4: Validate Completeness

Required Sections Checklist:

const requiredSections = [
  'Problem Statement',
  'Evidence',
  'Key Hypothesis',
  'Success Metrics',
  'Core Capabilities',
  'Implementation Phases',
  'Decisions Log',
];

// Verify all present
const missingRequiredSections = requiredSections.filter(section => !prdContent.includes(section));

if (missingRequiredSections.length > 0) {
  throw new Error(`Missing required sections: ${missingRequiredSections.join(', ')}`);
}

Quality Checks:

[ ] Problem Statement is specific (not vague)
[ ] Evidence includes data or user feedback
[ ] Hypothesis is measurable (includes metrics)
[ ] MoSCoW has at least 1 "Must" and 1 "Won't"
[ ] Implementation Phases have dependencies mapped
[ ] Decisions Log explains "why not X" for alternatives

Step 5: Write PRD

// Generate filename
const featureName = 'auth-refresh-tokens'; // from problem statement
const date = new Date().toISOString().split('T')[0]; // YYYY-MM-DD
const filename = `${featureName}-prd-${date}.md`;

// Write to specs directory
Write({
  file_path: `.claude/context/artifacts/specs/${filename}`,
  content: prdContent,
});

Output Location: .claude/context/artifacts/specs/{feature-name}-prd-{YYYY-MM-DD}.md

Provenance Header:

<!-- Agent: pm | Task: #{task-id} | Session: {date} -->

# PRD: {Feature Name}

**Version**: 1.0
**Author**: PM Agent
**Date**: {YYYY-MM-DD}
**Status**: Draft

Integration Points

PRD → Planner → Developer Flow

PM creates PRD:

## Implementation Phases

| #   | Phase   | Description       | Status  | Parallel | Depends | Plan Link |
| --- | ------- | ----------------- | ------- | -------- | ------- | --------- |
| 1   | Design  | Auth architecture | pending | No       | -       | -         |
| 2   | Backend | /refresh endpoint | pending | No       | 1       | -         |

Planner reads PRD:

TaskGet({ taskId: 'X' }) → Gets PRD location
Read PRD → Understands problem, decisions, phases
Selects next pending phase (dependencies met)
Creates implementation plan
Updates PRD with plan link:

| 1 | Design | Auth architecture | completed | No | - | [Plan](.claude/context/plans/impl-phase1-2026-02-09.md) |

Developer reads plan:

Planner's plan links back to PRD
Developer has full context: problem, decisions, rationale
Implements with understanding of "why"

Result:

Single source of truth: check PRD phases table for status
Traceability: PRD → Plan → Implementation
Context preservation: new devs can read PRD to understand feature

Required Sections Checklist

Before writing PRD, verify:

[ ] Problem Statement (specific, not vague)
[ ] Evidence (data, feedback, metrics)
[ ] Key Hypothesis (measurable outcome)
[ ] Success Metrics table (Metric | Target | How Measured)
[ ] Core Capabilities (MoSCoW with Must/Should/Could/Won't)
[ ] Implementation Phases table (# | Phase | Status | Depends | Plan Link)
[ ] Decisions Log (Decision | Choice | Alternatives | Rationale)
[ ] Users & Context (Primary User, Job to Be Done)
[ ] Technical Approach (Feasibility, dependencies)
[ ] Risks table (Risk | Likelihood | Mitigation)
[ ] Open Questions (unresolved items)

Common Patterns

Pattern 1: Feature Request → PRD

User: "Add dark mode to the app"

PM:
1. Problem: Users report eye strain in low-light conditions
2. Evidence: 200+ support tickets, 4.2 → 3.8 app rating mentions "too bright"
3. Hypothesis: Dark mode will reduce eye strain complaints by 60%
4. MoSCoW:
   - Must: System-default theme detection
   - Must: Manual toggle in settings
   - Should: Per-screen theme override
   - Won't: Automatic sunset-based switching (future)
5. Phases:
   - Phase 1: Design system color tokens
   - Phase 2: Implement theme provider
   - Phase 3: Update all screens
6. Write PRD → specs/dark-mode-prd-2026-02-09.md

Pattern 2: Ambiguous Request → Progressive Disclosure

User: "Make the app faster"

PM:
1. [Progressive Disclosure: 8-phase questioning]
   - What specific slowness? (App launch? Navigation? Data load?)
   - Where is evidence? (Metrics showing 5s app launch vs 2s competitor)
   - What outcome? (Launch time < 2s for 95th percentile)
2. [After gathering context]
   - Problem: App launch time 5s vs industry 2s
   - Hypothesis: Lazy loading modules will reduce launch to <2s
3. Write PRD → specs/app-launch-performance-prd-2026-02-09.md

Pattern 3: PRD Update During Implementation

Planner completes Phase 1 design:

Update PRD:
| 1 | Design | Auth architecture | completed | No | - | [Plan](.claude/context/plans/impl-phase1-2026-02-09.md) |
| 2 | Backend | /refresh endpoint | in_progress | No | 1 | [Plan](.claude/context/plans/impl-phase2-2026-02-09.md) |

Add decision to log:
| Token algorithm | RS256 | HS256 | RS256 for key rotation support |

Best Practices

DO:

Start with problem, not solution
Include evidence (data, quotes, metrics)
Make hypothesis measurable
Document "Won't" explicitly (prevent scope creep)
Map phase dependencies clearly
Record decisions with alternatives considered
Link phases to implementation plans
Update PRD as phases complete

DON'T:

Jump to solution without problem statement
Skip evidence gathering
Use vague success metrics ("make it better")
Forget to prioritize (everything is "Must")
Create phases without dependency mapping
Skip decision rationale
Let PRD become stale (update as phases progress)
Write PRD for trivial changes

Iron Laws

NEVER define a solution before articulating the problem with evidence — solution-first thinking generates features no one needs and hypotheses that cannot be validated.
ALWAYS include at least one "Won't" item in MoSCoW prioritization — explicit exclusions are what prevent scope creep and uncontrolled feature growth.
ALWAYS make the success hypothesis measurable with specific numeric targets — vague outcomes like "better UX" or "faster performance" cannot be validated or refuted.
ALWAYS map phase dependencies before implementation begins — undiscovered dependencies cause mid-sprint blockers and cascade delays across the entire roadmap.
NEVER let a PRD go stale during implementation — update phase statuses and the decisions log continuously as work progresses and discoveries are made.

Anti-Patterns

| Anti-Pattern | Why It Fails | Correct Approach | | --------------------------------------------------- | -------------------------------------------------------------------- | ----------------------------------------------------------------- | | Jumping to solution without a problem statement | Builds the wrong thing; no baseline to measure success | Define problem with evidence before proposing any solution | | Vague success metrics ("improve UX", "make faster") | Cannot validate hypothesis; no way to know if feature succeeded | Specify numeric targets: "-50% support tickets", "<2s load time" | | Marking everything as "Must" in MoSCoW | No prioritization leads to impossible scope and missed deadlines | Explicitly mark Won't items; treat Could/Should as negotiable | | Phases without dependency mapping | Parallel execution assumptions break when dependencies surface | Map "Depends" column before implementation; block accordingly | | Letting PRD go stale after kickoff | Developers lose context; decisions become invisible tribal knowledge | Update phase statuses and decisions log throughout implementation |

Example: Complete PRD

<!-- Agent: pm | Task: #42 | Session: 2026-02-09 -->

# PRD: JWT Refresh Token Implementation

**Version**: 1.0
**Author**: PM Agent
**Date**: 2026-02-09
**Status**: Draft

---

## Problem Statement

Mobile app users experience session expiration (1 hour timeout) during active use, forcing re-authentication and losing workflow context. This creates friction and frustration, particularly for users performing multi-step tasks.

## Evidence

- **Support Tickets**: 200+ complaints about "forced logout" in past 2 months
- **Analytics**: 35% of mobile sessions end with forced re-auth (vs 5% desktop)
- **User Feedback**: App store reviews mention "annoying login prompts" (4.2 → 3.8 rating)
- **Business Impact**: 15% cart abandonment rate correlates with session timeout

## Key Hypothesis

We believe adding JWT refresh tokens will reduce user re-authentication friction for mobile users.
We'll know we're right when session timeout complaints drop by 50% and mobile DAU increases by 10%.

## What We're NOT Building

- Biometric authentication integration (future Phase 2)
- Social login providers (separate initiative)
- Multi-device session management (v2.0)

## Success Metrics

| Metric                     | Target | How Measured            |
| -------------------------- | ------ | ----------------------- |
| Session timeout complaints | -50%   | Support ticket analysis |
| Mobile DAU                 | +10%   | Analytics dashboard     |
| Token refresh success rate | >95%   | Backend logs            |
| Forced re-auth rate        | <10%   | Analytics events        |

## Core Capabilities (MoSCoW)

| Priority | Capability                               | Rationale                                    |
| -------- | ---------------------------------------- | -------------------------------------------- |
| Must     | JWT refresh token endpoint               | Required for MVP - enables session extension |
| Must     | Token rotation on refresh                | Security best practice (OWASP)               |
| Must     | Secure token storage (Keychain/KeyStore) | Prevent token theft                          |
| Should   | Refresh token revocation                 | Allows user logout from all devices          |
| Should   | Token usage analytics                    | Monitoring and debugging                     |
| Could    | Configurable token lifetimes             | Admin flexibility                            |
| Won't    | Biometric auth integration               | Out of scope - future consideration          |
| Won't    | Push notification on token expiry        | Nice to have, defer to v2                    |

## Users & Context

**Primary User**: Mobile app user (iOS/Android) who experiences session expiration during active use (shopping, form filling, browsing)

**Current Behavior**: User logs in → performs task → session expires after 1 hour → forced to re-login → loses form data/cart context

**Trigger**: Session expiration during active use OR app returning from background after >1 hour

**Success State**: User stays logged in seamlessly for up to 30 days (refresh token lifetime), only re-authenticates when truly needed

**Job to Be Done**: When my session expires, I want to continue my work without re-entering credentials, so I can maintain my workflow momentum and complete my tasks.

## Solution Detail

### MVP Scope

**Phase 1**: Design auth architecture with refresh token flow
**Phase 2**: Implement backend /refresh endpoint with token rotation
**Phase 3**: Add refresh logic to mobile SDK (iOS/Android)
**Phase 4**: E2E tests for refresh flows
**Phase 5**: Add refresh metrics to monitoring dashboard

### User Flow

1. User logs in → receives access token (1 hour) + refresh token (30 days)
2. User makes API call → server validates access token
3. Access token expires → next API call returns 401
4. Mobile SDK detects 401 → calls /refresh with refresh token
5. Server validates refresh token → issues new access + refresh tokens
6. SDK retries original API call with new access token
7. User continues seamlessly (no re-login)

### Edge Cases

- Network failure during refresh → retry with exponential backoff
- Refresh token expired → force re-login with "session expired" message
- Refresh token revoked (password change) → force re-login
- Concurrent API calls during refresh → queue and retry after refresh completes

## Technical Approach

**Feasibility**: HIGH

**Dependencies**:

- Existing JWT library (jsonwebtoken) supports refresh
- Mobile SDK has secure storage (Keychain/KeyStore)
- Backend has session management infrastructure

**Integration Points**:

- Mobile SDK (iOS/Android) needs refresh interceptor
- Backend needs /refresh endpoint
- Database needs refresh token storage (w/ expiry)

**Architecture Notes**:

- Access token: 1 hour lifetime, stateless (JWT)
- Refresh token: 30 days lifetime, stateful (stored in DB)
- Token rotation: each refresh invalidates old token, issues new one
- Secure storage: Keychain (iOS), KeyStore (Android)

## Implementation Phases

| #   | Phase       | Description                                      | Status  | Parallel | Depends | Plan Link |
| --- | ----------- | ------------------------------------------------ | ------- | -------- | ------- | --------- |
| 1   | Design      | Auth architecture design with refresh token flow | pending | No       | -       | -         |
| 2   | Backend API | Implement /refresh endpoint with token rotation  | pending | No       | 1       | -         |
| 3   | Mobile SDK  | Add refresh logic to iOS/Android SDK             | pending | No       | 2       | -         |
| 4   | Testing     | E2E tests for refresh flows                      | pending | Yes      | 2,3     | -         |
| 5   | Monitoring  | Add refresh metrics to dashboard                 | pending | Yes      | 2       | -         |

## Decisions Log

| Decision         | Choice                             | Alternatives                           | Rationale                                               |
| ---------------- | ---------------------------------- | -------------------------------------- | ------------------------------------------------------- |
| Token storage    | Secure storage (Keychain/KeyStore) | Local storage, Session storage         | Security requirement - tokens are sensitive credentials |
| Refresh strategy | Automatic on 401                   | Manual user action, Proactive refresh  | Better UX - transparent to user, no extra UI            |
| Token lifetime   | Access: 1hr, Refresh: 30 days      | Access: 5min/90min, Refresh: 7/90 days | Balance security (short access) and UX (long refresh)   |
| Token algorithm  | RS256 (asymmetric)                 | HS256 (symmetric)                      | Enables key rotation, better for distributed systems    |
| Refresh rotation | Always rotate                      | Rotate on suspicious activity          | OWASP best practice, prevents token replay              |
| Storage location | Database                           | Redis, In-memory                       | Need persistent storage, DB already available           |

## Research Summary

**Market Context**:

- Auth0, Firebase, Okta all use refresh token pattern
- Industry standard: short-lived access + long-lived refresh
- OWASP recommends token rotation on every refresh
- JWT RFC 7519 and OAuth 2.0 RFC 6749 define patterns

**Technical Context**:

- Existing backend uses jsonwebtoken library (supports refresh)
- Mobile SDK has secure storage capabilities
- Backend has session management and database for token storage
- Average API latency: 100ms (refresh won't impact UX significantly)

**Feasibility Assessment**: HIGH

- All dependencies available
- No new infrastructure required
- Clear implementation path
- Low risk of scope creep

## Risks

| Risk                           | Likelihood | Mitigation                                                |
| ------------------------------ | ---------- | --------------------------------------------------------- |
| Token theft (XSS/MITM)         | Medium     | Use secure storage, HTTPS only, rotate on refresh         |
| Refresh loop (invalid token)   | Low        | Add exponential backoff, max 3 retries, fallback to login |
| Clock skew issues              | Low        | Use 5min grace period for exp validation                  |
| DB performance (token lookups) | Low        | Index refresh tokens, implement token cleanup job         |
| Concurrent refresh attempts    | Low        | Use mutex/lock during refresh, queue pending requests     |

## Open Questions

- [ ] What happens to active refresh tokens on password change? (Decision: revoke all)
- [ ] How do we handle token refresh during network outage? (Decision: retry with backoff)
- [ ] Should we notify user on refresh token expiration? (Decision: yes, with "session expired" message)
- [ ] Do we need per-device refresh tokens? (Decision: yes, for "logout all devices" feature)

---

_Generated: 2026-02-09_
_Status: Draft_

Related Skills

context-compressor - Progressive disclosure for unclear requirements
plan-generator - Break PRD phases into implementation tasks
research-synthesis - Gather evidence for problem statement

Assigned Agents

This skill is invoked by:

pm (Product Manager) - Primary user of this skill

Memory Protocol (MANDATORY)

Before starting: Read .claude/context/memory/learnings.md

Check for:

Previously created PRDs
Feature patterns in this codebase
Common decisions and rationales

After completing:

New PRD pattern → .claude/context/memory/learnings.md
Recurring decision → .claude/context/memory/decisions.md
PRD creation blocker → .claude/context/memory/issues.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

Agent Skills: PRD Generator Skill

Install this agent skill to your local

Skill Files