/specification-techniques

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:

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 accept