| name | prd-writing |
| description | Write Product Requirements Documents (PRDs) with structured workflow. Triggers: 'write a PRD', 'product spec', 'feature requirements', 'product requirements', 'create PRD', or any request to document product/feature specifications. Includes codebase analysis, iterative drafting, user story generation with acceptance criteria, and optional GitHub issue creation. |
PRD Writing Skill
Create comprehensive PRDs through Context Gathering → Codebase Analysis → Section Drafting → Validation → Issue Creation.
Core Workflow
1. Context Gathering
Ask 3-5 clarifying questions before drafting. Essential questions:
- What problem does this solve? Who experiences it?
- Who are the target users/personas?
- What does success look like? (measurable metrics)
- Technical constraints, dependencies, or integrations?
- Timeline, priority level, or phasing needs?
Context dumping encouraged: user research, competitive analysis, stakeholder requirements, existing specs.
⚠️ CRITICAL: Never skip context gathering, even when:
- You have access to existing specs/ideas
- The codebase is already implemented
- You think you understand the requirements
- The user seems eager to get to the PRD
Always ask the 3-5 clarifying questions FIRST. Existing context informs better questions, it doesn't replace them.
Readiness check: Move to drafting when you can discuss trade-offs without needing basics explained.
2. Codebase Analysis
When working in an existing codebase:
- Analyze architecture to identify integration points
- Review existing models, services, and patterns
- Assess technical constraints from current implementation
- Note naming conventions and code organization
- Identify reusable components vs. new development needed
3. Section Drafting
Use the PRD template in references/prd-template.md.
Iterative approach for each section:
- Ask clarifying questions if gaps exist
- Brainstorm 5-10 items with user
- Let user curate/prioritize
- Draft section
- Refine based on feedback
4. User Stories
See references/user-stories.md for detailed guidance.
Key requirements:
- Unique ID per story (format:
GH-001,GH-002, etc.) - Cover primary flows, alternative paths, and edge cases
- Include authentication/authorization if applicable
- Every story must be testable
- Clear acceptance criteria (specific, measurable)
5. Validation Checklist
Before finalizing, verify:
- Problem statement is clear and specific
- Target users/personas defined
- Success metrics are measurable
- All user interactions covered (primary + edge cases)
- Each user story is testable
- Acceptance criteria are unambiguous
- Scope boundaries (non-goals) explicit
- Dependencies and risks identified
- Auth/security requirements addressed (if applicable)
6. GitHub Issue Creation (Optional)
After PRD approval, offer to create GitHub issues:
- Ask: "Would you like me to create GitHub issues for these user stories?"
- If yes, create one issue per user story
- Use story ID as issue title prefix
- Include acceptance criteria in issue body
- Return list of created issue links
Common Mistakes to Avoid
- ❌ Jumping to drafting because you found idea.txt or existing specs
- ❌ Assuming implemented code means requirements are clear
- ❌ Skipping user input because you think you have enough context
- ✅ Use existing context to ask BETTER clarifying questions
Formatting Rules
- Title: Use title case only for main document title (
PRD: {Project Name}) - Headings: Sentence case for all other headings
- Output: Valid Markdown, no dividers/horizontal rules
- References: Refer to project conversationally ("the project", "this feature")
- Quality: Fix grammar, ensure correct casing of proper nouns
Output Location
Default: prd.md in project root. Ask user to confirm or specify alternative.