Prd Planner

PRD Planner

A PRD creation skill that uses persistent file-based planning to maintain coherent thinking and avoid "left-brain vs right-brain" context switching issues.

When This Skill Activates

This skill activates when you:

• Explicitly say "PRD", "prd", "create a PRD", or "产品需求文档"
• Say "product requirements document" or "产品需求"
• Mention "write a PRD for..."
• Say "PRD planning" or "PRD 设计"

If user says "design solution" or "architecture design" without mentioning PRD, use `architecting-solutions` instead.

The Core Philosophy

"PRD creation should be traceable, coherent, and persistent - not scattered across context switches."

This skill combines:

• PRD methodology (from architecting-solutions)
• File-based persistence (from planning-with-files)

To create a single, coherent PRD creation workflow that doesn't lose context.

4-File Pattern for PRD Creation

For every PRD project, create FOUR files:

Pick a SCOPE (short, unique, kebab-case slug) and use it as a prefix for all files.

docs/{scope}-prd-notes.md     → Store research, requirements, findings, options
docs/{scope}-prd-task-plan.md → Track PRD creation phases and progress
docs/{scope}-prd.md           → Product requirements (what & why)
docs/{scope}-tech.md          → Technical design (how)

File Purposes

Workflow

┌─────────────────────────────────────────────────────────────────┐
│                     PRD Creation Workflow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Initialize → Create 4 files with template                   │
│  2. Requirements → Gather to {scope}-prd-notes.md               │
│  2.5 Edge Cases → Scan codebase, infer patterns, ask smartly    │
│  3. Analysis → Research best practices, save to notes           │
│  4. Design → Propose architecture options (A/B/C), save to notes │
│  5. PRD → Write product requirements to {scope}-prd.md          │
│  6. Tech → Write technical design to {scope}-tech.md            │
│  7. Validate → Review with user, finalize                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
                    ↓
           All thinking persisted to files
                    ↓
              No context switching

Step 1: Initialize

Create the four files with templates:

{scope}-prd-task-plan.md

# PRD Task Plan: {Feature Name}

## Goal
Create a PRD and technical design for {feature description}.

## Owner
{User name/role}

## Phases
- [x] Phase 1: Initialize files ✓
- [ ] Phase 2: Gather requirements (CURRENT)
- [ ] Phase 3: Research & analysis
- [ ] Phase 4: Design solution
- [ ] Phase 5: Write PRD
- [ ] Phase 6: Write technical design
- [ ] Phase 7: Validate & finalize

## Status
**Currently in Phase 2** - Gathering requirements from user

## Progress Log
- {timestamp} - Phase 1 complete: Files initialized

{scope}-prd-notes.md

# PRD Notes: {Feature Name}

## Raw Requirements
(Add user requirements as they emerge)

## Constraints
(Add technical, business, time constraints)

## Inferred Patterns (from codebase)

| Edge Case | Source | Pattern Applied |
|-----------|--------|-----------------|
| (Filled after Step 2.5 codebase scan) | | |

## Edge Cases

### Auto-handled (following codebase patterns)
- (Filled after Step 2.5 analysis)

### Confirmed by User
- (Filled after user confirms edge case decisions)

### Open Questions
- (Track questions to ask user)

## Research Findings
(Add research on best practices, similar solutions)

## Architecture Options

- Option A: {Description}
  - Pros: {Advantages}
  - Cons: {Disadvantages}

- Option B: {Description}
  - Pros: {Advantages}
  - Cons: {Disadvantages}

- Option C: {Description}
  - Pros: {Advantages}
  - Cons: {Disadvantages}

**Selected**: Option {X}

{scope}-prd.md

# PRD: {Feature Name}

> Status: DRAFT
> Last updated: {timestamp}

## Table of Contents
- [Problem Statement](#problem-statement)
- [Goals and Non-Goals](#goals-and-non-goals)
- [Success Criteria](#success-criteria)
- [Scope](#scope)
- [Requirements](#requirements)
- [User Flows](#user-flows)
- [Implementation Plan](#implementation-plan)

---

## Problem Statement
_To be filled after requirements gathering_

## Goals and Non-Goals
### Goals
- {Specific achievable outcomes}

### Non-Goals
- {Explicit exclusions}

## Success Criteria
_To be filled with measurable criteria_

## Scope
### In Scope
- {Specific items included}

### Out of Scope
- {Specific items excluded}

... (rest of PRD sections)

{scope}-tech.md

# Technical Design: {Feature Name}

> Status: DRAFT
> Last updated: {timestamp}

## Overview
{High-level technical approach}

## Key Components
{List major components and their responsibilities}

## API Design
{API signatures, request/response formats}

## Data Flow
{How data flows through the system}

## Implementation Details
{Specific implementation notes}

## Migration Plan
{If applicable, how to migrate from existing system}

Step 2: Gather Requirements

Ask clarifying questions and save responses to {scope}-prd-notes.md:

Core Questions to Ask

1. Problem: What problem are we solving? 2. Users: Who will use this? 3. Success: How do we know it's successful? 4. Constraints: Any technical/time/budget constraints?

Save each answer to {scope}-prd-notes.md under appropriate section.

Always update `{scope}-prd-task-plan.md` after gathering info:

- [x] Phase 2: Gather requirements ✓
- [ ] Phase 2.5: Edge case analysis (CURRENT)
- [ ] Phase 3: Research & analysis

Step 2.5: Context-Aware Edge Case Analysis

Before asking users about edge cases, scan the codebase first to infer existing patterns. This reduces redundant questions and ensures consistency with the project.

Detailed reference: See references/edge-case-analysis.md for full scanning commands and output formats.

Quick Process

1. Scan codebase for existing patterns (delete strategy, error handling, empty states, pagination) 2. Identify requirement type (CRUD, State Workflow, Async, Data Display, Form, File) 3. Generate smart assumptions - patterns found in code don't need user confirmation 4. Ask only when needed - no precedent, multiple patterns, or business decision required

When to Ask Users

Output to Notes File

Update {scope}-prd-notes.md with:

## Inferred Patterns (from codebase)
| Edge Case | Source | Pattern Applied |
|-----------|--------|-----------------|
| Delete | `src/models/User.ts:45` | Soft delete |

## Edge Cases
### Auto-handled (following codebase patterns)
- Empty list → Use existing EmptyState component

### Confirmed by User
- Concurrent edit: Last write wins (confirmed {date})

Update task plan:

- [x] Phase 2.5: Edge case analysis ✓
- [ ] Phase 3: Research & analysis (CURRENT)

Step 3: Research & Analysis

Research best practices and save to {scope}-prd-notes.md:

# Search for similar implementations
grep -r "keyword" packages/ --include="*.ts"

# Search web for best practices
web search "best practices for {feature}"

Save findings to {scope}-prd-notes.md → Research Findings section.

Step 4: Design Solution

Propose architecture with trade-offs, save to {scope}-prd-notes.md:

## Architecture Options

- Option A: {Description}
  - Pros: {Advantages}
  - Cons: {Disadvantages}

- Option B: {Description}
  - Pros: {Advantages}
  - Cons: {Disadvantages}

- Option C: {Description}
  - Pros: {Advantages}
  - Cons: {Disadvantages}

**Selected**: Option {X} - because {reason}

Step 5: Write PRD

Read {scope}-prd-notes.md and synthesize into polished PRD:

1. Read {scope}-prd-notes.md to understand:
   - Requirements gathered
   - Research findings
   - Architecture decision (which option was selected)

2. Write {scope}-prd.md with:
   - Clear problem statement
   - Goals and Non-Goals (explicit exclusions)
   - Measurable success criteria (specific numbers/timings)
   - Scope (In Scope / Out of Scope)
   - Functional requirements
   - Non-functional requirements
   - User flows
   - Implementation plan (high level)

3. Reference tech doc: "See {scope}-tech.md for technical design"

Step 6: Write Technical Design

1. Read {scope}-prd-notes.md for selected architecture option

2. Write {scope}-tech.md with:
   - Overview (technical approach summary)
   - Key Components (what pieces, responsibilities)
   - API Design (signatures, contracts)
   - Data Flow (how data moves through system)
   - Implementation Details (specific notes)
   - Migration Plan (if applicable)

Step 7: Validate & Finalize

Review with user: 1. Present PRD summary 2. Ask for feedback 3. Incorporate changes 4. Mark Phase 7 complete

Important Rules

Phase Transitions

Update {scope}-prd-task-plan.md after each phase with checkbox ✓ and timestamp.

Completing a PRD

Mark all phases complete, set status to "✅ COMPLETE", log final deliverables.

File Cleanup (Optional)

After PRD is complete:

• Keep {scope}-prd-notes.md for reference (shows decision process)
• Archive {scope}-prd-task-plan.md or delete
• Final outputs are {scope}-prd.md and {scope}-tech.md

Quick Start Template

# PRD Task Plan: {Feature}

## Goal
Create PRD and technical design for {description}

## Phases
- [ ] Initialize 4 files
- [ ] Gather requirements
- [ ] Research & analysis
- [ ] Design solution (A/B/C options)
- [ ] Write PRD
- [ ] Write technical design
- [ ] Validate & finalize

## Status
Phase 1: Initializing files

Why This Works

References

• planning-with-files - File-based planning methodology
• architecting-solutions - Non-PRD solution and architecture design
• Edge case scanning: references/edge-case-analysis.md

---

Auto-Trigger (Follow-up Metadata)

When this skill completes, record or run supported follow-ups: 1. self-improving-agent (background) - Propose reusable patterns 2. session-logger (auto) - Save session context when supported

PRD Planner

A PRD creation skill that uses persistent file-based planning to maintain coherent thinking and avoid context switching issues.

Overview

PRD Planner combines PRD methodology with file-based persistence (planning-with-files) to create a single, coherent workflow that doesn't lose context during PRD creation.

The Problem

Traditional PRD creation suffers from:

• Context switching - Requirements in memory, then forgotten
• Lost thoughts - Research findings not captured
• "Left brain vs right brain" - Different thinking modes conflict
• Inconsistent output - Each PRD looks different

The Solution

Use a 4-file pattern that persists all thinking. Pick a SCOPE (short, unique, kebab-case slug) and prefix all files:

docs/{scope}-prd-task-plan.md → Progress tracking
docs/{scope}-prd-notes.md     → Research & requirements
docs/{scope}-prd.md           → Final PRD output
docs/{scope}-tech.md          → Technical design output

Installation

mkdir -p ~/.claude/skills
ln -s ~/Documents/code/GitHub/agent-playbook/skills/prd-planner ~/.claude/skills/prd-planner

Usage

# Simply ask for a PRD
"Create a PRD for user authentication"

# The skill will:
# 1. Create 4 files in docs/
# 2. Gather requirements (saved to notes)
# 3. Research best practices (saved to notes)
# 4. Design architecture (saved to notes)
# 5. Synthesize into PRD (reads from notes)
# 6. Write technical design (reads from notes)
# 7. Validate with you

Workflow

┌─────────────────────────────────────────────────────────────────┐
│                     PRD Creation Workflow                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  1. Initialize → Create 4 files with template                   │
│  2. Requirements → Gather to {scope}-prd-notes.md               │
│  3. Analysis → Research best practices, save to notes           │
│  4. Design → Propose architecture, save to notes                │
│  5. Synthesize → Read notes, write PRD, update plan             │
│  6. Tech → Write technical design from notes                    │
│  7. Validate → Review with user, finalize                       │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘

File Structure

docs/
├── {scope}-prd-task-plan.md  # Progress tracking with checkboxes
├── {scope}-prd-notes.md      # All research and requirements
├── {scope}-prd.md            # Final polished PRD
└── {scope}-tech.md           # Technical design

Key Principles

Activation

This skill activates when user says:

• "Create a PRD..."
• "PRD for..."
• "产品需求文档"
• "Product requirements document"

Different from:

• architecting-solutions - For "design solution" or "architecture design"
• planning-with-files - For general task planning (not PRD-specific)

License

MIT

Edge Case Analysis Reference

This document provides detailed guidance for Step 2.5: Context-Aware Edge Case Analysis.

Codebase Pattern Scanning Commands

Run these searches to understand how the project handles common scenarios:

# Delete strategy (soft delete vs hard delete)
grep -r "softDelete\|isDeleted\|deletedAt\|removed" src/ --include="*.ts" --include="*.tsx"

# Error handling patterns
grep -r "toast\|notification\|alert\|snackbar\|message\." src/ --include="*.tsx"

# Empty state handling
grep -r "empty\|noData\|EmptyState\|placeholder" src/ --include="*.tsx"

# Pagination patterns
grep -r "pageSize\|limit\|offset\|pagination\|perPage" src/ --include="*.ts"

# Loading state patterns
grep -r "loading\|isLoading\|pending\|Skeleton" src/ --include="*.tsx"

# Validation patterns
grep -r "validate\|validator\|yup\|zod\|schema" src/ --include="*.ts"

Requirement Type Classification

Smart Assumptions Output Format

Record inferred patterns in {scope}-prd-notes.md:

## Inferred Patterns (from codebase)

| Edge Case | Source | Pattern Applied |
|-----------|--------|-----------------|
| Delete strategy | `src/models/User.ts:45` uses `deletedAt` | Soft delete |
| Error display | `src/utils/toast.ts` global Toast | Toast notification |
| Empty state | `src/components/EmptyState.tsx` exists | Reuse EmptyState component |
| Pagination | `src/hooks/usePagination.ts:12` default 20 | 20 items per page |
| Loading | `src/components/Skeleton.tsx` exists | Use Skeleton component |

When to Ask Users

Only ask about edge cases when:

1. No precedent in codebase - First time the project encounters this scenario 2. Multiple patterns exist - Codebase has inconsistent approaches 3. Business decision required - Technical analysis cannot determine the answer

Question Categories

User Confirmation Format

## Edge Cases Requiring Confirmation

Based on the feature requirements, these edge cases need your input:

### 1. Concurrent Edit Handling
When two users edit the same record simultaneously:
- [ ] A: Last write wins (simpler, may lose data)
- [ ] B: Show conflict dialog (better UX, more complex)
- [ ] C: Lock record during edit (prevents conflicts, may block users)

### 2. Cascade Delete Behavior
When deleting a parent record with children:
- [ ] A: Block deletion, show warning
- [ ] B: Cascade delete all children
- [ ] C: Orphan children (set parent_id to null)

**Note**: Questions not listed above will follow existing codebase patterns.

Edge Cases Section in Notes File

## Edge Cases

### Auto-handled (following codebase patterns)
- Empty list → Use existing `EmptyState` component
- Network error → Retry 3 times (from `src/utils/api.ts:23`)
- Form validation → Real-time with inline errors (from `src/hooks/useForm.ts`)

### Confirmed by User
- Concurrent edit: Last write wins (confirmed {date})
- Cascade delete: Block and warn (confirmed {date})

### Open Questions
- (List any remaining questions)