doravidan/prd

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:

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

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:

1. Define component types and interfaces
2. Create base component structure
3. Implement component logic and state
4. Add styling and polish

backend-api Pattern:

1. Define data models and types
2. Implement core service logic
3. Create API routes/controllers
4. Add integration tests and documentation

backend-auth Pattern:

1. Define user and auth types
2. Implement password hashing
3. Create token management
4. Add auth routes
5. Implement auth middleware
6. 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:

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

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

# 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]

---

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

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

# 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

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