555 lines
15 KiB
Markdown
555 lines
15 KiB
Markdown
---
|
|
name: specification-techniques
|
|
description: Master techniques for writing clear, complete product specifications and requirements documents (PRDs). Use when defining feature requirements, writing user stories, creating acceptance criteria, documenting API specifications, aligning cross-functional teams, reducing ambiguity, covering edge cases, or translating product vision into actionable development tasks. Covers PRD structure, user story formats (INVEST, 3Cs, Given-When-Then), Jobs-to-be-Done, use cases, non-functional requirements, and specification best practices.
|
|
---
|
|
|
|
# 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:
|
|
|
|
1. **Overview** - Problem, goals, non-goals, success metrics
|
|
2. **Background** - Context, user research, competitive analysis
|
|
3. **User Personas** - Primary/secondary users, use cases
|
|
4. **Requirements** - Functional and non-functional requirements
|
|
5. **User Experience** - Flows, wireframes, interaction details
|
|
6. **Technical Considerations** - Architecture, APIs, performance
|
|
7. **Success Criteria** - Launch criteria, key metrics
|
|
8. **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. Vague Requirements
|
|
|
|
**Bad:** "System should have good performance"
|
|
|
|
**Good:** "Dashboard loads in <2 seconds (p95) for 10,000 concurrent users"
|
|
|
|
---
|
|
|
|
### 3. Over-Specification
|
|
|
|
**Bad:** "Use bcrypt with cost factor 12, store in CHAR(60) column"
|
|
|
|
**Good:** "Passwords hashed with industry-standard algorithm meeting OWASP guidelines"
|
|
|
|
---
|
|
|
|
### 4. 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
|
|
```
|
|
|
|
---
|
|
|
|
### 5. Ignoring Edge Cases
|
|
|
|
**Bad:** "User can upload a file"
|
|
|
|
**Good:**
|
|
```
|
|
User can upload file:
|
|
- Happy: File <10MB, supported format → Success
|
|
- Error: File >10MB → "File exceeds 10MB limit"
|
|
- Error: Unsupported format → "Only JPG, PNG, PDF allowed"
|
|
- Error: Network failure → Auto-retry 3x, then "Upload failed. Retry?"
|
|
```
|
|
|
|
**Complete Guide:** See `references/specification-anti-patterns.md` for detailed anti-patterns with examples and fixes.
|
|
|
|
---
|
|
|
|
## Reference Guides
|
|
|
|
### Comprehensive Guides
|
|
|
|
**User Story Writing:**
|
|
- `references/user-story-writing-guide.md`
|
|
- INVEST criteria in depth
|
|
- The 3 Cs framework
|
|
- Story splitting patterns
|
|
- User story vs job story vs use case
|
|
|
|
**Acceptance Criteria:**
|
|
- `references/acceptance-criteria-guide.md`
|
|
- All three formats explained
|
|
- Writing testable criteria
|
|
- Covering happy/unhappy paths
|
|
- Edge case documentation
|
|
|
|
**Anti-Patterns:**
|
|
- `references/specification-anti-patterns.md`
|
|
- Common mistakes and how to avoid them
|
|
- Solution masquerading as problem
|
|
- Vague requirements
|
|
- Over-specification
|
|
|
|
**Best Practices:**
|
|
- `references/specification-best-practices.md`
|
|
- Core principles
|
|
- Structure and organization
|
|
- Writing style and clarity
|
|
- Collaboration and communication
|
|
- Progressive elaboration
|
|
|
|
---
|
|
|
|
## Templates and Tools
|
|
|
|
### Ready-to-Use Templates
|
|
|
|
**Documentation:**
|
|
- `assets/prd-structure-template.md` - Complete PRD template
|
|
- `assets/user-story-template.md` - User story with INVEST
|
|
- `assets/job-story-template.md` - Jobs-to-be-Done format
|
|
- `assets/use-case-template.md` - Detailed use case structure
|
|
|
|
**Checklists:**
|
|
- `assets/edge-case-checklist.md` - 100+ point systematic coverage
|
|
- `assets/non-functional-requirements-template.md` - NFR documentation
|
|
|
|
---
|
|
|
|
## Summary
|
|
|
|
**Good Specifications:**
|
|
- Start with problem and user needs (the "why")
|
|
- Are specific, measurable, and testable
|
|
- Cover happy paths, unhappy paths, and edge cases
|
|
- Specify behavior and constraints (the "what")
|
|
- Leave implementation flexible (the "how")
|
|
- Use visual aids and concrete examples
|
|
- Create shared understanding through conversation
|
|
|
|
**Remember:** Specifications are conversation starters, not contracts. Focus on creating shared understanding between product, engineering, design, and QA.
|
|
|
|
---
|
|
|
|
## Related Skills
|
|
|
|
- `prd-templates` - PRD templates and examples
|
|
- `user-story-templates` - User story templates and patterns
|
|
- `user-research-techniques` - Understanding user needs and requirements
|