Stats
Actions
Tags
From ai-pm-copilot
Teaches PRD structure, user stories, acceptance criteria, API specs, and non-functional requirements for clear feature definition and team alignment.
How this skill is triggered — by the user, by Claude, or both
Slash command
/ai-pm-copilot:specification-techniquesThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Structured methods for translating product vision into clear, actionable requirements that align teams, reduce ambiguity, and enable successful execution.
assets/edge-case-checklist.mdassets/job-story-template.mdassets/non-functional-requirements-template.mdassets/prd-structure-template.mdassets/use-case-template.mdassets/user-story-template.mdreferences/acceptance-criteria-guide.mdreferences/specification-anti-patterns.mdreferences/specification-best-practices.mdreferences/user-story-writing-guide.mdStructured methods for translating product vision into clear, actionable requirements that align teams, reduce ambiguity, and enable successful execution.
Specification techniques help you answer "what" and "why" clearly while leaving "how" flexible for the team to determine. They create shared understanding without being prescriptive about implementation.
Core Principle: The value of specifications isn't in comprehensive documentation—it's in the conversations and shared understanding they create. A 3-sentence user story that everyone understands is better than a 30-page spec no one reads.
Origin: Modern specification techniques evolved from software engineering (Karl Wiegers), agile methodologies (Mike Cohn), and design thinking (Alan Cooper).
Key Insight: Good specifications enable teams to build the right thing, while bad specifications constrain teams and lead to rework.
Auto-loaded by agents:
requirements-engineer - For PRDs, user stories, acceptance criteria, and NFRsUse when you need to:
A well-structured PRD contains:
Complete Template: See assets/prd-structure-template.md for full PRD structure with examples and best practices.
Problem Statement:
What: Clear description of the problem
Who: Who experiences this problem
Impact: Business/user impact with data
Current: What users do today
Goals and Non-Goals:
Success Metrics:
Example:
Problem: Users miss critical alerts when not in app, leading to 40% missed events.
Goal: Reduce missed alerts from 40% to <15% via email notifications.
Non-Goals:
- SMS notifications (future scope)
- Customizable notification frequency (v1: fixed)
Success Metrics:
- 60% opt-in to email notifications
- 25% reduction in missed alerts
- <2% unsubscribe rate
As a [user type]
I want [capability]
So that [benefit]
Purpose: Placeholder for conversation, not complete specification.
Example:
As a project manager
I want to assign tasks to team members
So that everyone knows their responsibilities
Framework for evaluating user story quality (Mike Cohn):
Complete Guide: See references/user-story-writing-guide.md for detailed explanations, examples, and story splitting patterns.
Template: See assets/user-story-template.md for comprehensive user story template with INVEST checklist.
Card: Brief story description (placeholder) Conversation: Discuss details during planning/refinement (most important) Confirmation: Acceptance criteria (how to verify done)
Key Insight: The conversation is more valuable than the written artifact.
Format 1: Given-When-Then (Gherkin/BDD)
Given [precondition/context]
When [action/event]
Then [expected outcome]
And [additional outcome]
Best for: Behavior-driven development, sequential workflows, automated testing
Example:
Given I am on the login page
When I enter valid credentials and click "Login"
Then I am redirected to my dashboard
And I see a welcome message with my name
Format 2: Checklist Style
Acceptance Criteria:
- [ ] Criterion 1
- [ ] Criterion 2
- [ ] Criterion 3
Best for: Simple features, independent criteria, non-sequential requirements
Example:
- [ ] User can upload JPG, PNG, GIF files
- [ ] Maximum file size is 10MB
- [ ] Upload progress bar shows percentage
- [ ] Error shown if file too large
Format 3: Example-Based
Scenario: [Description]
Input: [What user provides]
Output: [What system produces]
Best for: Complex calculations, validation rules, data transformations
Example:
Scenario 1: Valid email
Input: [email protected]
Output: Email accepted
Scenario 2: Missing @ symbol
Input: userexample.com
Output: Error "Email must include @ symbol"
Complete Guide: See references/acceptance-criteria-guide.md for comprehensive guide to writing testable acceptance criteria with all three formats, examples, and best practices.
When [situation/context]
I want to [motivation]
So I can [expected outcome]
Difference from User Stories:
Example:
When I'm in a meeting and need to reference previous discussions
I want to quickly search message history by keyword
So I can find relevant context without disrupting the meeting flow
Complete Template: See assets/job-story-template.md for detailed job story structure, examples, and when to use vs. user stories.
Detailed interaction scenarios documenting step-by-step system behavior.
Components:
Example Structure:
Use Case: User Registers for Account
Primary Actor: New user
Goal: Create account to access platform
Main Success Scenario:
1. User enters email, password, name
2. System validates inputs
3. System creates account
4. System sends verification email
5. User clicks verification link
6. System activates account
Complete Template: See assets/use-case-template.md for comprehensive use case template with examples of alternative flows, exception handling, and special requirements.
Document behavior for:
1. Input Validation - Empty inputs, special characters, invalid formats 2. Permissions - Unauthenticated, insufficient privileges, expired sessions 3. State Handling - Empty state, loading state, error state, full state 4. Boundary Conditions - Zero, one, maximum, just over maximum 5. Time-Based - Expired tokens, time zones, scheduling 6. Network Issues - Timeouts, server errors, rate limiting
Example:
Error Scenario: Payment fails due to insufficient funds
User Experience:
- Error message: "Payment declined - insufficient funds. Please use a different payment method."
System Behavior:
- Transaction rolled back
- User not charged
- Order not created
- Error logged
Recovery Action:
- User can update payment method and retry
Complete Checklist: See assets/edge-case-checklist.md for systematic 100+ point checklist covering all edge case categories with examples and error handling templates.
Performance Requirements:
Security Requirements:
Reliability Requirements:
Accessibility Requirements:
Example:
Performance: Page loads in <2 seconds (p95)
Security: All PII encrypted at rest (AES-256)
Reliability: 99.9% uptime (max 8.7 hours downtime/year)
Accessibility: WCAG 2.1 Level AA compliant
Complete Template: See assets/non-functional-requirements-template.md for comprehensive NFR documentation covering all categories with specific metrics and verification methods.
Always begin with problem statement before jumping to solutions:
Problem Statement Template:
Problem: [What problem exists?]
Impact: [Who is affected and how?]
Evidence: [Data, research, user quotes]
Goal: [What would success look like?]
Vague (Bad): "System should be fast"
Specific (Good): "Page loads in <2 seconds (p95), measured via Lighthouse"
Avoid Ambiguous Terms:
Happy Path: Successful scenario
Unhappy Paths:
Example:
Happy: User logs in with valid credentials → Dashboard
Error: User enters wrong password → Error message, stay on login
Edge: Session expires during form entry → Preserve data, re-authenticate
Too Prescriptive (Bad):
"Use Material-UI Autocomplete component with Redux state management"
Behavioral (Good):
"User can search for other users by name, see suggestions as they type, select one or multiple users. Selection persists across page refreshes."
Let engineering decide: component library, state management
Use diagrams for:
Use examples for:
Bad: "We need a chatbot on the homepage"
Good:
Problem: 60% of support tickets are basic questions. Users can't find answers quickly.
Explored solutions: Chatbot, improved search, interactive FAQ
Bad:
As a user, I want notifications
Good:
As a user, I want email notifications
So that I'm aware of critical events
Acceptance Criteria:
- Given payment fails, when processor returns error, then email sent within 5 minutes
- Given I'm in settings, when I toggle notifications, then preference saves immediately
Complete Guide: See references/specification-anti-patterns.md for detailed anti-patterns with examples and fixes.
prd-templates - PRD templates and examplesuser-story-templates - User story templates and patternsuser-research-techniques - Understanding user needs and requirementsnpx claudepluginhub slgoodrich/agents --plugin ai-pm-copilotCreates clear, testable specifications from feature descriptions with user stories, acceptance criteria, and measurable success metrics.
Generates structured product specifications from feature requests, issues, or descriptions. Produces user stories with EARS acceptance criteria, Given-When-Then scenarios, and PRD documents.
Create clear, unambiguous product requirements that prevent costly rework and enable execution. Use when scoping features, defining acceptance criteria, or ensuring alignment between product, design, and engineering.