slgoodrich/agents/specification-techniques

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. 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.