references/prd_template.md
# PRD Template Structure
This template defines the structure for Product Requirements Documents optimized for AI coding tools.
---
## Document Sections
### 1. Document Header
```markdown
# [Product Name] — Product Requirements Document
**Version:** 1.0
**Date:** [YYYY-MM-DD]
**Author:** [Name]
**Status:** Draft | Review | Approved
```
### 2. Executive Summary
One paragraph (3-5 sentences) covering:
- What the product does
- Who it's for
- The core problem it solves
- Expected outcome
**Example:**
> "ChurnGuard is a SaaS tool that predicts which customers are at risk of churning and recommends retention actions. It targets B2B SaaS companies with 100+ customers who struggle with reactive churn management. By analyzing usage patterns, support tickets, and billing data, ChurnGuard provides a daily risk score and suggested interventions. The expected outcome is a 15-25% reduction in monthly churn."
### 3. Problem Statement
Structure:
- **Current state:** What exists now and why it's broken
- **Pain points:** 3-5 specific problems users face
- **Impact:** Business cost of not solving this
### 4. Goals & Success Metrics
| Goal | Metric | Target | Measurement Method |
|------|--------|--------|-------------------|
| Primary goal | KPI | Specific number | How to measure |
| Secondary goal | KPI | Specific number | How to measure |
**Example:**
| Goal | Metric | Target | Measurement Method |
|------|--------|--------|-------------------|
| Reduce churn | Monthly churn rate | < 3% | Billing system |
| Increase retention actions | Actions taken per alert | > 60% | In-app tracking |
### 5. User Personas
For each persona:
```markdown
#### [Persona Name]
- **Role:** [Job title]
- **Goals:** What they're trying to accomplish
- **Pain points:** Current frustrations
- **Technical proficiency:** Low / Medium / High
- **Usage context:** When and how they'll use this
```
### 6. Functional Requirements
Use this format for EVERY feature:
```markdown
#### FR-[XXX]: [Feature Name]
**Description:** [One sentence explaining what this does]
**User story:** As a [persona], I want to [action] so that [benefit].
**Acceptance criteria:**
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
- [ ] [Specific, testable criterion]
**Priority:** P0 (MVP) | P1 (Important) | P2 (Nice to have)
**Dependencies:** [List any dependencies on other features]
```
**Priority definitions:**
- P0 — Must have for launch. Product doesn't work without it.
- P1 — Important for first version. Include if time permits.
- P2 — Nice to have. Can wait for v2.
### 7. Non-Functional Requirements
Cover these categories as applicable:
```markdown
#### Performance
- Page load time: [target]
- API response time: [target]
- Concurrent users supported: [number]
#### Security
- Authentication method: [OAuth, JWT, etc.]
- Data encryption: [at rest, in transit]
- Compliance requirements: [GDPR, SOC2, etc.]
#### Scalability
- Expected initial load: [users/requests]
- Growth target: [users/requests in X months]
- Scaling approach: [horizontal, vertical, auto-scale]
#### Availability
- Uptime target: [99.9%, etc.]
- Backup frequency: [daily, hourly]
- Disaster recovery: [RTO, RPO]
```
### 8. Technical Architecture
```markdown
#### System Overview
[High-level description of the system architecture]
#### Technology Stack
- **Frontend:** [Framework, language]
- **Backend:** [Framework, language]
- **Database:** [Type, service]
- **Hosting:** [Provider, service]
- **Key libraries:** [List major dependencies]
#### Architecture Diagram (Description)
[Describe the system flow in text — AI tools will interpret this]
Example:
"User requests flow through a Next.js frontend → API Gateway → Express.js backend → PostgreSQL database. Background jobs run on a separate worker service using Bull queues. File uploads go to S3 with CloudFront CDN."
```
### 9. API Specifications
For each endpoint:
```markdown
#### [HTTP Method] /api/[endpoint]
**Purpose:** [What this endpoint does]
**Authentication:** Required | Optional | None
**Request:**
```json
{
"field": "type — description"
}
```
**Response (200):**
```json
{
"field": "type — description"
}
```
**Error responses:**
- 400: [When this occurs]
- 401: [When this occurs]
- 404: [When this occurs]
```
### 10. UI/UX Requirements
For each screen/view:
```markdown
#### [Screen Name]
**Purpose:** [What the user accomplishes here]
**Key elements:**
- [Element 1]: [Description and behavior]
- [Element 2]: [Description and behavior]
**User flow:**
1. User does [action]
2. System responds with [response]
3. User sees [result]
**States:**
- Empty state: [What shows when no data]
- Loading state: [Loading behavior]
- Error state: [Error handling]
```
### 11. Data Models
```markdown
#### [Model Name]
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| id | UUID | Yes | Primary key |
| field_name | string | Yes | Description |
| created_at | timestamp | Yes | Creation timestamp |
**Relationships:**
- [Relationship type] to [Other Model]
**Indexes:**
- [field_name] — for [query type]
```
### 12. Integration Points
For each external service:
```markdown
#### [Service Name]
**Purpose:** [Why this integration exists]
**Integration type:** REST API | Webhook | SDK | OAuth
**Data exchanged:**
- Inbound: [What we receive]
- Outbound: [What we send]
**Authentication:** [How we authenticate]
**Rate limits:** [If applicable]
**Fallback behavior:** [What happens if this fails]
```
### 13. Edge Cases & Error Handling
```markdown
#### Edge Cases
| Scenario | Expected Behavior |
|----------|-------------------|
| [Scenario 1] | [How system handles it] |
| [Scenario 2] | [How system handles it] |
#### Error Handling Strategy
- **User-facing errors:** [How to display]
- **System errors:** [How to log/alert]
- **Retry logic:** [When and how to retry]
- **Graceful degradation:** [What still works when X fails]
```
### 14. Testing Requirements
```markdown
#### Unit Tests
- [Component/Function] — [What to test]
#### Integration Tests
- [Flow/Integration] — [What to verify]
#### E2E Tests
- [User journey] — [Critical path to test]
#### Performance Tests
- [Scenario] — [Target metric]
```
### 15. Implementation Notes for AI
**THIS SECTION IS CRITICAL — It tells the AI coding tool how to build this.**
```markdown
#### Build Order
1. [First thing to build — usually data models]
2. [Second thing — usually API endpoints]
3. [Third thing — usually frontend components]
...
#### File Structure Suggestion
```
/src
/components
/pages
/api
/lib
/types
```
#### Critical Implementation Details
- [Detail 1]: [Specific instruction]
- [Detail 2]: [Specific instruction]
#### Code Style Preferences
- [Language/framework conventions]
- [Naming conventions]
- [File organization rules]
#### Libraries to Use
- [Library] for [purpose] — [why this one]
#### Libraries to Avoid
- [Library] — [reason]
#### Common Pitfalls
- [Pitfall 1]: [How to avoid]
- [Pitfall 2]: [How to avoid]
#### Testing Approach
- Write tests for [priority areas]
- Skip tests for [low-risk areas]
- Use [testing library] for [purpose]
```
---
## Template Usage Notes
1. **Not all sections required** — Skip sections that don't apply. A landing page PRD doesn't need API specs.
2. **Specificity beats completeness** — One well-defined feature is better than ten vague ones.
3. **Acceptance criteria are mandatory** — If you can't write testable acceptance criteria, the feature isn't defined enough.
4. **Priorities matter** — P0 features should be 30-40% of total. If everything is P0, nothing is.
5. **AI-specific section is not optional** — This is what makes the PRD actually useful for AI coding tools.
SKILL.md
---
name: prd-generator
description: Generates professional PRD (Product Requirements Document) files optimized for AI coding tools. Takes a rough product idea, asks clarifying questions, and outputs a structured PDF ready to feed into AI coding assistants.
---
# PRD Generator
## Purpose
Transform a rough product idea into a comprehensive, AI-ready Product Requirements Document (PDF) through targeted questions and structured output.
---
## Execution Logic
**Check $ARGUMENTS first to determine execution mode:**
### If $ARGUMENTS is empty or not provided:
Respond with:
"prd-generator loaded, describe your product idea"
Then wait for the user to provide their product concept in the next message.
### If $ARGUMENTS contains content:
Proceed immediately to Task Execution (skip the "loaded" message).
---
## Task Execution
### 1. MANDATORY: Read Reference Files FIRST
**BLOCKING REQUIREMENT — DO NOT SKIP THIS STEP**
Before doing ANYTHING else, use the Read tool to read:
- `./references/prd_template.md`
This template defines the exact structure your PRD must follow. **DO NOT PROCEED** to Step 2 until you have read this file.
### 2. Skip Business Context
**This skill intentionally DOES NOT read FOUNDER_CONTEXT.md.** PRDs are standalone documents that should contain all necessary context within them.
### 3. Analyze Initial Input
From the user's initial description, extract what's available:
- Product name or working title
- Core problem being solved
- Target users/audience
- Key features mentioned
- Technical preferences (if any)
- Constraints or requirements (if any)
### 4. Ask Clarifying Questions
**Use AskUserQuestion tool** to gather missing information. Ask up to 7 questions maximum, but fewer is better — stop as soon as you have enough to build a comprehensive PRD.
**Question Bank (priority order):**
| # | Question | Why it matters | Skip if... |
|---|----------|----------------|------------|
| 1 | Who is the primary user? What's their role and technical level? | Shapes all UX decisions and feature complexity | User persona is clearly described |
| 2 | What's the core problem this solves? What happens if users don't have this? | Defines the value proposition and success metrics | Problem statement is explicit |
| 3 | What are the 3-5 must-have features for launch (P0)? | Prevents scope creep, focuses MVP | Features are already listed with clear priority |
| 4 | What technology preferences or constraints exist? (Language, framework, hosting) | Determines technical architecture section | Tech stack is specified |
| 5 | Are there any integrations required? (Auth providers, APIs, third-party services) | Identifies dependencies and integration complexity | No external services mentioned or user says standalone |
| 6 | What does success look like? Any specific metrics to track? | Defines goals and success metrics section | Metrics or goals are already stated |
| 7 | Any design preferences or existing brand guidelines to follow? | Shapes UI/UX requirements section | Design is flexible or already described |
**Question strategy:**
- Ask 2-4 questions per batch using AskUserQuestion
- If the first batch answers provide enough detail, stop asking
- Never ask more than 7 questions total
- Group related questions when possible
### 5. Generate the PRD
Using the template structure from `./references/prd_template.md`, create a complete PRD:
1. **Fill every applicable section** from the template
2. **Be specific** — vague requirements produce vague code
3. **Write acceptance criteria** for every feature — make them testable
4. **Prioritize ruthlessly** — P0 should be 30-40% of features
5. **The "Implementation Notes for AI" section is mandatory** — this is what makes it AI-ready
### 6. Save and Convert to PDF
**Step 6a: Create output folder**
```bash
mkdir -p ./prd_outputs/[Project Name]/
```
Use the product name with spaces, e.g., `./prd_outputs/Churn Prevention Tool/`
**Step 6b: Save markdown file**
Write the PRD content to:
```
./prd_outputs/[Project Name]/[project_name]_PRD.md
```
Use snake_case for the filename, e.g., `churn_prevention_tool_PRD.md`
**Step 6c: Convert to PDF**
Run:
```bash
npx md-to-pdf "./prd_outputs/[Project Name]/[project_name]_PRD.md"
```
This creates `[project_name]_PRD.pdf` in the same folder.
### 7. Confirm Output
Tell the user:
- Where the PDF is saved (full path)
- Where the markdown source is saved
- Brief summary of what's in the PRD
---
## Writing Rules
### Core Rules
- Every feature MUST have testable acceptance criteria
- Use specific numbers, not vague terms ("loads in <2s" not "loads quickly")
- P0 features should be 30-40% of total features — if everything is P0, nothing is
- Data models must include field types and relationships
- API specs must include request/response examples
### PRD-Specific Rules
- Executive summary: 3-5 sentences maximum
- Problem statement: Must include current state, pain points, and business impact
- User personas: Maximum 3 primary personas — more creates confusion
- Tech architecture: Describe data flow in plain English — AI tools interpret this better than complex diagrams
- Implementation Notes for AI section: This is mandatory, never skip it
### Format Rules
- Use markdown headers consistently (# for title, ## for sections, ### for subsections)
- Use tables for structured data (metrics, data models, API specs)
- Use code blocks for JSON examples and technical specs
- Use checkboxes for acceptance criteria
---
## Output Format
The PRD follows the structure in `./references/prd_template.md`. Here's a condensed example:
```markdown
# TaskFlow — Product Requirements Document
**Version:** 1.0
**Date:** 2024-01-15
**Author:** PRD Generator
**Status:** Draft
## Executive Summary
TaskFlow is a task management tool for remote engineering teams...
## Problem Statement
**Current state:** Teams use disconnected tools...
**Pain points:**
1. Context switching between tools
2. No visibility into team workload
3. Async communication gaps
**Impact:** 5+ hours/week lost per engineer...
## Goals & Success Metrics
| Goal | Metric | Target | Measurement |
|------|--------|--------|-------------|
| Reduce context switching | Tool switches/day | < 10 | Analytics |
## User Personas
### Engineering Manager
- **Role:** Manages 5-10 engineers
- **Goals:** Visibility into sprint progress...
## Functional Requirements
### FR-001: Task Creation
**Description:** Users can create tasks with title, description, assignee, and due date.
**User story:** As an engineer, I want to create tasks quickly so that I capture work items without friction.
**Acceptance criteria:**
- [ ] Task creation completes in < 500ms
- [ ] Title field is required, minimum 3 characters
- [ ] Due date defaults to end of current sprint
**Priority:** P0
...
## Implementation Notes for AI
### Build Order
1. Database schema (PostgreSQL)
2. API endpoints (Express.js)
3. Frontend components (React)
4. Auth integration (Clerk)
### Libraries to Use
- Prisma for ORM — type-safe, great DX
- TanStack Query for data fetching — handles caching
- Tailwind CSS for styling — utility-first, fast iteration
### Critical Implementation Details
- All dates stored as UTC, converted to user timezone on display
- Use optimistic updates for task status changes
- Implement soft deletes for all user-generated content
```
---
## References
**This file MUST be read using the Read tool before task execution (see Step 1):**
| File | Purpose |
|------|---------|
| `./references/prd_template.md` | Complete PRD structure with all 15 sections, format examples, and usage notes |
**Why this matters:** The template ensures every PRD follows a consistent, comprehensive structure that AI coding tools can parse and implement. Skipping the template results in incomplete PRDs that miss critical sections.
---
## Quality Checklist (Self-Verification)
### Pre-Execution Check
- [ ] I read `./references/prd_template.md` before starting
- [ ] I have the template structure in context
### Question Check
- [ ] I asked 7 or fewer questions total
- [ ] I only asked questions where information was genuinely missing
- [ ] Questions were batched (2-4 per AskUserQuestion call)
### PRD Content Check
- [ ] Executive summary is 3-5 sentences
- [ ] Every feature has acceptance criteria (checkboxes)
- [ ] P0 features are ~30-40% of total (not everything)
- [ ] Data models include field types
- [ ] API specs include request/response examples
- [ ] "Implementation Notes for AI" section is complete
### Output Check
- [ ] Markdown file saved to `./prd_outputs/[Project Name]/`
- [ ] PDF generated via `npx md-to-pdf`
- [ ] User informed of file locations
**If ANY check fails → fix before completing.**
---
## Defaults & Assumptions
Use these unless the user specifies otherwise:
- **Document version:** 1.0
- **Status:** Draft
- **Author:** PRD Generator
- **Tech stack:** Modern web (React + Node.js + PostgreSQL) unless specified
- **Hosting:** Cloud-native (Vercel/Railway/AWS) unless specified
- **Auth:** Third-party (Clerk/Auth0) unless building custom
- **Priority split:** ~35% P0, ~40% P1, ~25% P2
- **User personas:** Maximum 3 unless complexity demands more
- **API style:** REST unless GraphQL is specified
Document any assumptions made in the PRD output.