PRD Generation Skill

Generate detailed, context-aware Product Requirements Documents (PRDs) through interactive conversation.

Trigger

This skill activates when the user asks to:

•Create a PRD
•Write requirements for a feature
•Plan a new feature
•Generate user stories

Process

Step 1: Gather Context

First, analyze the project to understand its tech stack:

bash

# Read PROJECT_SPEC.md if it exists (generated by /setup-project)
cat PROJECT_SPEC.md 2>/dev/null

# Or analyze manually
cat package.json 2>/dev/null | head -50
cat tsconfig.json 2>/dev/null | head -20
ls -la src/ 2>/dev/null | head -20

Extract:

•Language (TypeScript, JavaScript, Python, Go)
•Framework (React, Next.js, Express, FastAPI)
•Test framework (Vitest, Jest, Pytest)
•Linting tool (ESLint, Biome, Ruff)
•Module system (ES modules, CommonJS)

Step 2: Clarifying Questions

Ask 3-5 targeted questions based on the feature type. Format with lettered options:

code

Before I create the PRD, I have a few questions:

**1. What is the primary goal of this feature?**
   a) [Option 1 - most common]
   b) [Option 2]
   c) [Option 3]
   d) Something else (please specify)

**2. Who is the target user?**
   a) End users (customers)
   b) Internal users (admins, staff)
   c) Developers (API consumers)
   d) All of the above

**3. [Context-specific question]**
   ...

Question Templates by Feature Type:

Authentication Feature:

•What auth methods? (Email/password, OAuth, Magic link, MFA)
•What happens after login? (Redirect, modal, return to page)
•Session duration requirements?

API Feature:

•RESTful or GraphQL?
•Authentication required?
•Rate limiting needed?
•What data models involved?

UI Component Feature:

•Desktop, mobile, or responsive?
•Theme/dark mode support?
•Accessibility requirements?
•Animation preferences?

Data/Backend Feature:

•Database type? (PostgreSQL, MongoDB, Redis)
•Real-time updates needed?
•Caching requirements?
•Data validation rules?

Wait for the user's answers before proceeding.

Step 3: Generate Intelligent User Stories

Based on project context and feature type, generate appropriately-sized stories.

Story Pattern Selection:

Tech Stack	Feature Type	Pattern
React/Next.js	UI Component	react-ui
React/Next.js	API Route	nextjs-api
Express/Fastify	API	backend-api
Express/Fastify	Auth	backend-auth
FastAPI/Django	API	python-api
Node.js	General	node-feature
Python	General	python-feature

Story Templates:

react-ui Pattern:

•Define component types and interfaces
•Create base component structure
•Implement component logic and state
•Add styling and polish

backend-api Pattern:

•Define data models and types
•Implement core service logic
•Create API routes/controllers
•Add integration tests and documentation

backend-auth Pattern:

•Define user and auth types
•Implement password hashing
•Create token management
•Add auth routes
•Implement auth middleware
•Add protected route tests

Story Sizing Rules:

•Each story completable in ONE RALPH iteration
•Maximum 4-6 acceptance criteria per story
•Stories ordered by dependency (types → logic → API → UI)
•Every story includes quality gate criteria

Step 4: Generate PRD Document

Create the PRD in Markdown format:

markdown

# PRD: [Feature Name]

## Overview
[2-3 sentence summary of what we're building and why]

## Project Context
- **Project:** [Project name]
- **Language:** [TypeScript/JavaScript/Python/etc.]
- **Framework:** [React/Express/FastAPI/etc.]
- **Test Framework:** [Vitest/Jest/Pytest/etc.]

## Goals
1. [Primary goal]
2. [Secondary goal]
3. [Tertiary goal]

## User Stories

### US-001: [Story Title]
**As a** [user type]
**I want** [capability]
**So that** [benefit]

**Acceptance Criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Another criterion]
- [ ] [TypeScript compiles / Type hints pass]
- [ ] [Tests pass]

**Priority:** 1 (Highest - foundation/types)

### US-002: [Story Title]
...

## Non-Goals
- [What we are explicitly NOT doing]
- [Scope limitations]

## Technical Considerations
- [Architecture decisions]
- [Dependencies to add]
- [Performance requirements]

## Quality Gates
All stories must pass before completion:
- [ ] TypeScript compiles without errors (if applicable)
- [ ] [Linter] passes
- [ ] Tests pass ([test framework])

## Open Questions
- [Unresolved decisions]
- [Items needing clarification]

Step 5: Generate prd.json

Convert the PRD to RALPH-compatible JSON:

json

{
  "project": "[Feature Name]",
  "branchName": "ralph/[feature-slug]",
  "description": "[Overview text]",
  "createdAt": "[Today's date: YYYY-MM-DD]",
  "projectContext": {
    "name": "[Project name]",
    "language": "[typescript/javascript/python/go]",
    "framework": "[React/Express/FastAPI/none]",
    "hasTypes": true,
    "testFramework": "[vitest/jest/pytest/unknown]"
  },
  "existingPatterns": {
    "moduleSystem": "[ES modules/CommonJS]",
    "namingStyle": "[camelCase/kebab-case/snake_case]",
    "testFramework": "[vitest/jest/pytest]",
    "linter": "[eslint/biome/ruff/none]",
    "hasTypes": true,
    "strictTypes": true
  },
  "userStories": [
    {
      "id": "US-001",
      "title": "[Story title]",
      "description": "[Full story description]",
      "acceptanceCriteria": [
        "[Criterion 1]",
        "[Criterion 2]",
        "[Quality gate criterion]"
      ],
      "priority": 1,
      "passes": false,
      "notes": ""
    }
  ]
}

Step 6: Initialize Progress File

Create progress.txt with discovered patterns:

markdown

# Progress Log - ralph/[feature-slug]

Started: [Date]
Feature: [Feature description]

## Project Context
- Language: [language]
- Framework: [framework]
- Test Framework: [test framework]
- Types: [TypeScript/Python hints/None]

## Codebase Patterns
- Module system: [ES modules/CommonJS]
- Naming convention: [camelCase/kebab-case]
- Linting: [eslint/biome/ruff]
- Import order: [Node builtins → External → Local]
- Source code in: [src/ or lib/ or root]
- Tests in: [tests/ or __tests__ or spec/]

## Quality Commands
```bash
[typecheck command]
[lint command]
[test command]

code


### Step 7: Save Files

```bash
# Create tasks directory
mkdir -p tasks

# Save PRD markdown
cat > tasks/prd-[feature-slug].md << 'EOF'
[PRD content]
EOF

# Save prd.json
cat > prd.json << 'EOF'
[JSON content]
EOF

# Save progress.txt
cat > progress.txt << 'EOF'
[Progress content]
EOF

Step 8: Output Summary

code

## PRD Created Successfully

### Files:
- tasks/prd-[feature-slug].md (human-readable PRD)
- prd.json (RALPH-compatible format)
- progress.txt (initialized with project patterns)

### Summary:
- **Feature:** [Feature name]
- **Branch:** ralph/[feature-slug]
- **Stories:** [count] total
  - Priority 1: [count] (foundation)
  - Priority 2: [count] (core logic)
  - Priority 3: [count] (API/integration)
  - Priority 4+: [count] (UI/polish)

### Story Overview:
1. US-001: [Title] (Priority 1)
2. US-002: [Title] (Priority 2)
...

### Next Steps:
1. Review prd.json and adjust stories if needed
2. Review progress.txt patterns
3. Create feature branch: git checkout -b ralph/[feature-slug]
4. Start RALPH: ./scripts/ralph/ralph.sh 20

Or run manually:
   /ralph-run

Acceptance Criteria Templates

TypeScript/JavaScript Projects:

•TypeScript compiles without errors
•ESLint/Biome passes
•Tests pass (Vitest/Jest)
•No any types (if strict mode)

Python Projects:

•Type hints complete
•Ruff/Pylint passes
•Pytest passes
•Mypy passes (if typed)

Go Projects:

•go build succeeds
•golangci-lint passes
•go test passes

Universal:

•Code reviewed
•Documentation updated
•Error handling complete
•Edge cases covered

Example: React UI Component PRD

User Request: "Create a PRD for a dark mode toggle"

Generated PRD:

markdown

# PRD: Dark Mode Toggle

## Overview
Add a dark mode toggle to the application settings that persists user preference and respects system settings.

## Project Context
- **Project:** my-react-app
- **Language:** TypeScript
- **Framework:** React (Vite)
- **Test Framework:** Vitest

## User Stories

### US-001: Define theme types and context
**As a** developer
**I want** TypeScript types and React context for theming
**So that** components can access and update the theme

**Acceptance Criteria:**
- [ ] Theme type defined: 'light' | 'dark' | 'system'
- [ ] ThemeContext created with provider
- [ ] useTheme hook exported
- [ ] TypeScript compiles without errors

**Priority:** 1

### US-002: Implement theme persistence
**As a** user
**I want** my theme preference to persist across sessions
**So that** I don't have to set it every time

**Acceptance Criteria:**
- [ ] Theme stored in localStorage
- [ ] System preference detected via matchMedia
- [ ] Theme loaded on app initialization
- [ ] Tests pass

**Priority:** 2

### US-003: Create toggle component
**As a** user
**I want** a toggle button in settings
**So that** I can switch between light and dark mode

**Acceptance Criteria:**
- [ ] Toggle component renders correctly
- [ ] Click toggles theme
- [ ] Visual feedback shows current theme
- [ ] Accessible (keyboard, screen reader)
- [ ] ESLint passes
- [ ] Tests pass

**Priority:** 3

### US-004: Apply theme styles
**As a** user
**I want** the UI to change appearance based on theme
**So that** I have a comfortable viewing experience

**Acceptance Criteria:**
- [ ] CSS variables for theme colors
- [ ] Components use theme variables
- [ ] Smooth transition between themes
- [ ] All quality gates pass

**Priority:** 4

Rules

•Story Sizing - Each story MUST be completable in ONE RALPH iteration
•Dependency Order - Order stories: types → logic → API → UI
•Quality Gates - EVERY story includes language-specific quality criteria
•Specificity - Avoid vague criteria like "works well" or "looks good"
•Context Awareness - Use PROJECT_SPEC.md patterns when available
•Branch Naming - Always ralph/[feature-slug] format