specification-techniques

What this skill does

# 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: [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.

---

## 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
```

**Com