| name | specification-techniques |
| description | Techniques for writing clear product specifications, user stories, and acceptance criteria. Use when defining feature requirements, writing user stories, creating acceptance criteria, or reducing spec ambiguity. Trigger on: 'write a spec', 'acceptance criteria for this feature', 'user story format', 'define requirements', 'Given-When-Then'. |
Specification Techniques
Structured methods for translating product vision into clear, actionable requirements that align teams, reduce ambiguity, and enable successful execution.
Overview
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.
When to Use This Skill
Auto-loaded by agents:
requirements-engineer - For PRDs, user stories, acceptance criteria, and NFRs
Use when you need to:
- Write product requirements documents (PRDs)
- Create user stories with acceptance criteria
- Define feature requirements clearly
- Document edge cases and error handling
- Specify non-functional requirements (performance, security)
- Align cross-functional teams on scope
- Translate product vision into development tasks
Product Requirements Documents (PRDs)
Core Structure
A well-structured PRD contains:
- Overview - Problem, goals, non-goals, success metrics
- Background - Context, user research, competitive analysis
- User Personas - Primary/secondary users, use cases
- Requirements - Functional and non-functional requirements
- User Experience - Flows, wireframes, interaction details
- Technical Considerations - Architecture, APIs, performance
- Success Criteria - Launch criteria, key metrics
- Timeline & Resources - Milestones, team, risks
Complete Template: See assets/prd-structure-template.md for full PRD structure with examples and best practices.
Essential PRD Components
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:
- Goals: What you want to achieve (measurable)
- Non-Goals: What you're explicitly not doing (sets boundaries)
Success Metrics:
- Specific, measurable outcomes
- Baseline → Target values
- Timeline for achievement
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
User Stories
The Standard Format
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
INVEST Criteria
Framework for evaluating user story quality (Mike Cohn):
- I - Independent: Can be developed in any order
- N - Negotiable: Details flexible, not a contract
- V - Valuable: Delivers user or business value
- E - Estimable: Team can estimate effort
- S - Small: Fits within one sprint (1-5 days)
- T - Testable: Clear acceptance criteria
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.
The 3 Cs Framework (Ron Jeffries)
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.
Acceptance Criteria
Three Formats
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: user@example.com
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.
Job Stories (Jobs-to-be-Done)
Format
When [situation/context]
I want to [motivation]
So I can [expected outcome]
Difference from User Stories:
- Focuses on context/situation (not persona)
- Emphasizes motivation (not implementation)
- Better for discovering underlying needs
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.
Use Cases
Structure
Detailed interaction scenarios documenting step-by-step system behavior.
Components:
- Primary actor and goal
- Preconditions and postconditions
- Main success scenario (happy path)
- Alternative flows (variations)
- Exception flows (error handling)
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.
Edge Cases and Error Handling
Systematic Coverage
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.
Non-Functional Requirements
Key Categories
Performance Requirements:
- Response time (page loads, API calls)
- Throughput (requests per second)
- Scalability (concurrent users, data volume)
Security Requirements:
- Authentication (MFA, password policies)
- Authorization (RBAC, least privilege)
- Data protection (encryption, GDPR compliance)
Reliability Requirements:
- Availability (uptime %)
- Data integrity (backups, recovery)
- Fault tolerance (failover, retries)
Accessibility Requirements:
- WCAG 2.1 compliance
- Keyboard navigation
- Screen reader compatibility
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.
Specification Best Practices
Start with Why
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?]
Be Specific and Measurable
Vague (Bad): "System should be fast"
Specific (Good): "Page loads in <2 seconds (p95), measured via Lighthouse"
Avoid Ambiguous Terms:
- "Fast" → Specific time (< 2 seconds)
- "Good" → Specific criteria
- "User-friendly" → Task completion metrics
- "Secure" → OWASP Top 10 compliant
Cover Happy and Unhappy Paths
Happy Path: Successful scenario
Unhappy Paths:
- Error cases (invalid input, permission denied)
- Edge cases (boundary conditions, rare scenarios)
- Network failures (timeouts, service down)
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
Specify Behavior, Not Implementation
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
Include Visual Aids
Use diagrams for:
- User flows
- State machines
- Data flows
- Wireframes/mockups
Use examples for:
- Input validation rules
- Calculations
- Data transformations
Anti-Patterns to Avoid
1. Solution Masquerading as Problem
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
2. Missing Acceptance Criteria
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.
Troubleshooting
"Developers say my specs are ambiguous": You're likely writing what the feature does but not the edge cases. For every requirement, ask: "What happens when the input is empty? Invalid? Extremely large?" Add Given-When-Then acceptance criteria for each case.
"My user stories are too big to estimate": Apply the INVEST criteria -- specifically the S (Small). If a story can't be completed in one sprint, split it. Split by workflow step, data variation, or happy path vs. error handling.
"Stakeholders and engineers interpret the spec differently": Add concrete examples. Abstract specs create ambiguity. For every requirement, include at least one specific input/output example showing exactly what happens.
Related Skills
prd-templates - PRD templates and examplesuser-story-templates - User story templates and patternsuser-research-techniques - Understanding user needs and requirements
