Spec Writing

Spec Writing

Overview

Create clear, complete, and testable specifications from natural language feature descriptions. Specifications focus on user value and business needs, avoiding implementation details.

When To Use

• Creating new feature specifications
• Refining existing specifications
• Writing user stories and acceptance criteria
• Defining success criteria

When NOT To Use

• Generating implementation tasks - use task-planning

Core Principles

Focus on user value and business needs rather than implementation details. Avoid specifying technology choices in requirement definitions unless strictly necessary. Ensure every requirement is testable and verifiable with measurable criteria. Limit clarification markers; make informed assumptions based on industry standards and document them explicitly.

Specification Structure

Mandatory Sections

1. Overview/Context: What problem does this solve? 2. User Scenarios: Who uses it and how? 3. Functional Requirements: What must it do? 4. Success Criteria: How do we know it works?

Optional Sections

• Success Criteria (when performance/security critical)
• Edge Cases (when special handling needed)
• Dependencies (when external systems involved)
• Assumptions (when decisions made with incomplete info)

See: modules/specification-structure.md for detailed templates and guidelines

Quality Checklist

• [ ] No implementation details present
• [ ] Requirements are testable and unambiguous
• [ ] Success criteria are measurable
• [ ] User scenarios cover primary flows
• [ ] Edge cases identified
• [ ] Scope clearly bounded

Success Criteria Quick Reference

Good (User-focused, Measurable, Technology-agnostic)

• "Users complete checkout in under 3 minutes"
• "System supports 10,000 concurrent users"
• "95% of searches return results in under 1 second"

Bad (Implementation-focused, Internal metrics)

• "API response time under 200ms" -> Use: "Pages load in under 2 seconds"
• "Redis cache hit rate above 80%" -> Use: "Frequently accessed data loads with no noticeable delay"
• "React components render efficiently" -> Use: "UI updates appear with no visible frame drops"

See: modules/success-criteria-patterns.md for detailed examples and conversion process

Related Skills

• speckit-orchestrator: Workflow coordination
• task-planning: Converting specs to tasks

Troubleshooting

Common Issues

If specifications are too vague, use the success-criteria-patterns module to enforce measurable outcomes. If implementation details leak into specs, review against the "Core Principles" and refactor to focus on user behavior.

Checklist Quality Dimensions

Overview

Checklists are unit tests for requirements writing - they validate the quality, clarity, and completeness of requirements in a given domain, NOT implementation correctness.

Core Principle

Test the Requirements, Not the Implementation

Every checklist item MUST evaluate the REQUIREMENTS THEMSELVES, not whether code works correctly.

What Checklists Are NOT

• NOT "Verify the button clicks correctly"
• NOT "Test error handling works"
• NOT "Confirm the API returns 200"
• NOT checking if code/implementation matches the spec

What Checklists ARE

• "Are visual hierarchy requirements defined for all card types?" (completeness)
• "Is 'prominent display' quantified with specific sizing/positioning?" (clarity)
• "Are hover state requirements consistent across all interactive elements?" (consistency)
• "Are accessibility requirements defined for keyboard navigation?" (coverage)
• "Does the spec define what happens when logo image fails to load?" (edge cases)

Quality Dimensions

1. Completeness

Question: Are all necessary requirements present?

Pattern: "Are [requirement type] defined/documented for [scenario]?"

Examples:

• "Are error handling requirements defined for all API failure modes? [Gap]"
• "Are accessibility requirements specified for all interactive elements? [Completeness]"
• "Are mobile breakpoint requirements defined for responsive layouts? [Gap]"

2. Clarity

Question: Are requirements unambiguous and specific?

Pattern: "Is [vague term] quantified/clarified with specific criteria?"

Examples:

• "Is 'fast loading' quantified with specific timing thresholds? [Clarity, Spec §NFR-2]"
• "Are 'related episodes' selection criteria explicitly defined? [Clarity, Spec §FR-5]"
• "Is 'prominent' defined with measurable visual properties? [Ambiguity, Spec §FR-4]"

3. Consistency

Question: Do requirements align without conflicts?

Pattern: "Are requirements consistent between [section A] and [section B]?"

Examples:

• "Do navigation requirements align across all pages? [Consistency, Spec §FR-10]"
• "Are card component requirements consistent between landing and detail pages? [Consistency]"

4. Measurability

Question: Can requirements be objectively verified?

Pattern: "Can [requirement] be objectively measured/verified?"

Examples:

• "Are visual hierarchy requirements measurable/testable? [Acceptance Criteria, Spec §FR-1]"
• "Can 'balanced visual weight' be objectively verified? [Measurability, Spec §FR-2]"

5. Coverage

Question: Are all scenarios/edge cases addressed?

Pattern: "Are requirements defined for [scenario class]?"

Examples:

• "Are requirements defined for zero-state scenarios (no episodes)? [Coverage, Edge Case]"
• "Are concurrent user interaction scenarios addressed? [Coverage, Gap]"
• "Are requirements specified for partial data loading failures? [Coverage, Exception Flow]"

6. Edge Cases

Question: Are boundary conditions and error scenarios defined?

Pattern: "Is default behavior specified when [edge condition]?"

Examples:

• "Is default behavior defined when images fail to load? [Edge Case, Gap]"
• "Are rollback requirements defined for migration failures? [Gap]"
• "Are requirements specified for partial data loading? [Coverage, Exception Flow]"

7. Success Criteria

Question: Are quality attributes specified (performance, security, accessibility)?

Pattern: "Are [success criteria type] requirements quantified/specified?"

Examples:

• "Are performance requirements quantified with specific metrics? [Clarity]"
• "Are security requirements defined for sensitive data? [Completeness]"
• "Are accessibility requirements specified for keyboard navigation? [Gap]"

Item Structure

Each checklist item should follow this pattern:

- [ ] CHK### Question format asking about requirement quality [Dimension, Reference]

Components:

• Question format: Asks about what's WRITTEN (or not written) in requirements
• Quality dimension: [Completeness/Clarity/Consistency/Coverage/Measurability/Edge Case/Success Criteria]
• Reference: [Spec §X.Y] for existing requirements, [Gap] for missing ones

Traceability Requirements

• MINIMUM: ≥80% of items MUST include at least one traceability reference
• References: [Spec §X.Y], [Gap], [Ambiguity], [Conflict], [Assumption]
• If no ID system exists: "Is a requirement & acceptance criteria ID scheme established? [Traceability]"

Prohibited Patterns

These patterns test implementation, not requirements:

• Any item starting with "Verify", "Test", "Confirm", "Check" + implementation behavior
• References to code execution, user actions, system behavior
• "Displays correctly", "works properly", "functions as expected"
• "Click", "navigate", "render", "load", "execute"
• Test cases, test plans, QA procedures
• Implementation details (frameworks, APIs, algorithms)

Required Patterns

These patterns test requirements quality:

• "Are [requirement type] defined/specified/documented for [scenario]?"
• "Is [vague term] quantified/clarified with specific criteria?"
• "Are requirements consistent between [section A] and [section B]?"
• "Can [requirement] be objectively measured/verified?"
• "Are [edge cases/scenarios] addressed in requirements?"
• "Does the spec define [missing aspect]?"

Specification Structure

Mandatory Sections

Every specification must include these four sections to be considered complete.

1. Overview/Context

Purpose: Establish the problem being solved and why it matters.

What to Include:

• Problem statement: What pain point does this address?
• Business value: Why invest in this now?
• Target users: Who benefits from this?
• Success definition: What does "done" look like at a high level?

When to Expand:

• Complex features touching multiple user personas
• Features requiring stakeholder alignment
• Features with significant business impact

Template:

## Overview

**Problem**: [1-2 sentences describing the user pain point]

**Value**: [1-2 sentences on business impact or user benefit]

**Users**: [Who uses this feature and in what context]

**Success**: [High-level outcome when complete]

Example:

## Overview

**Problem**: Users abandon checkout because they can't easily review their order before completing purchase.

**Value**: Reducing checkout abandonment by 15% would increase revenue by $2M annually.

**Users**: All e-commerce customers, especially first-time buyers who need confidence before purchase.

**Success**: Checkout completion rate increases and customer support questions about orders decrease.

Assumptions

Purpose: Document conditions taken as given that inform this specification.

What to Include:

• Conditions assumed true that, if proven false, would

invalidate parts of this specification

• Scope boundaries accepted without verification
• Environmental or organizational givens

Template:

## Assumptions

Explicit assumptions that inform this specification.
Document any conditions taken as given that, if proven
false, would invalidate parts of this specification.

- [List assumptions here]

2. User Scenarios

Purpose: Show how real users interact with the feature in context.

What to Include:

• Primary user flows (happy path)
• User motivations and goals
• Starting state and ending state
• Context of use

When to Expand:

• Multiple user personas with different needs
• Complex workflows spanning multiple sessions
• Features replacing existing processes

Template:

## User Scenarios

### Scenario 1: [User Type] - [Goal]
**Context**: [When/why the user needs this]
**Flow**:
1. [User action or starting point]
2. [Next step]
3. [Outcome]

**Expected Result**: [What the user achieves]

Example:

## User Scenarios

### Scenario 1: First-Time Buyer - Review Order Before Purchase
**Context**: User has added items to cart and is ready to checkout but wants to verify everything is correct.

**Flow**:
1. User clicks "Proceed to Checkout" from shopping cart
2. User sees order summary with item details, quantities, and prices
3. User reviews shipping address and payment method
4. User confirms and completes purchase

**Expected Result**: User feels confident they're ordering the right items and has opportunity to catch errors.

3. Functional Requirements

Purpose: Define what the system must do, without specifying how.

What to Include:

• Required capabilities (what users can do)
• Data inputs and outputs
• Validation rules
• Business rules
• Integration points (at a high level)

When to Expand:

• Features with complex business logic
• Features requiring data transformations
• Features with many validation rules

Template:

## Functional Requirements

### Core Capabilities
- [ ] The system must [capability]
- [ ] Users can [action]
- [ ] The system will [behavior]

### Validation Rules
- [ ] [Field/input] must [constraint]
- [ ] [Condition] triggers [response]

### Business Rules
- [ ] When [condition], then [outcome]

Example:

## Functional Requirements

### Core Capabilities
- [ ] Users can view complete order summary before final purchase
- [ ] Order summary displays all line items with quantities and prices
- [ ] Users can edit quantities directly from order summary
- [ ] System calculates totals including tax and shipping

### Validation Rules
- [ ] Out-of-stock items must show availability warning
- [ ] Minimum order amount enforced before checkout button enables

### Business Rules
- [ ] Tax calculation based on shipping address
- [ ] Free shipping threshold applies after discounts

4. Success Criteria

Purpose: Define measurable outcomes that prove the feature works.

What to Include:

• Quantifiable metrics
• Observable user behaviors
• Performance targets
• Quality thresholds

When to Expand:

• Features with performance requirements
• Features affecting business KPIs
• Features requiring A/B testing validation

Template:

## Success Criteria

### User Outcomes
- [ ] [Percentage] of users [behavior]
- [ ] Users complete [task] in under [time]

### Performance Targets
- [ ] [Operation] completes in under [time]
- [ ] System supports [number] concurrent [users/operations]

### Quality Metrics
- [ ] [Metric] improves by [percentage]
- [ ] Error rate below [threshold]

Example:

## Success Criteria

### User Outcomes
- [ ] 90% of users review order summary before completing checkout
- [ ] Users complete checkout in under 3 minutes from cart to confirmation

### Performance Targets
- [ ] Order summary loads in under 1 second
- [ ] System supports 5,000 concurrent checkouts

### Quality Metrics
- [ ] Checkout abandonment rate decreases by 15%
- [ ] Order correction requests decrease by 30%

Optional Sections

Include these sections when they add value, not by default.

Success Criteria

When to Include:

• Performance requirements beyond normal expectations
• Security or compliance needs
• Accessibility requirements
• Scalability targets

Example:

## Success Criteria

### Performance
- Response times under heavy load
- Concurrent user targets

### Security
- Data encryption requirements
- Authentication/authorization needs

### Accessibility
- WCAG compliance level
- Screen reader support

Edge Cases

When to Include:

• Known error conditions that need special handling
• Unusual but possible scenarios
• Boundary conditions

Example:

## Edge Cases

- User has 100+ items in cart
- User's session expires during checkout
- Payment gateway is temporarily unavailable
- Item goes out of stock during checkout

Dependencies

When to Include:

• External systems or services required
• Other features that must be completed first
• Third-party integrations

Example:

## Dependencies

- Payment gateway integration (external)
- Inventory system API (internal)
- User authentication feature (prerequisite)

Assumptions

When to Include:

• Decisions made without full information
• Simplifications for initial implementation
• Constraints accepted for this version

Example:

## Assumptions

- Users have JavaScript enabled
- Payment gateway supports all major credit cards
- Tax rates available via API in all supported regions
- Initial launch supports US customers only

Section Guidelines

When to Include Optional Sections

Include Success Criteria when:

• Performance is critical to user experience
• Security/compliance is required
• Scalability beyond normal is needed

Include Edge Cases when:

• Known error scenarios need specific handling
• Boundary conditions affect design
• Risk mitigation is important

Include Dependencies when:

• External systems affect timeline
• Prerequisites must be tracked
• Integration complexity is high

Include Assumptions when:

• Decisions made with incomplete information
• Scope deliberately limited
• Future expansion planned

When to Exclude Optional Sections

Skip sections that:

• Contain implementation details
• Duplicate other documentation
• Add no concrete information
• Are empty or speculative

Examples to Skip:

• Success Criteria: "Should be fast" (too vague)
• Edge Cases: "Might have issues with large files" (not specific)
• Dependencies: "Uses a database" (obvious)
• Assumptions: "Users want good UX" (too generic)

Quality Guidelines

Good Section Content

• Specific and testable
• User-focused language
• Measurable where possible
• Technology-agnostic

Poor Section Content

• Implementation details
• Vague requirements
• Obvious statements
• Technology choices

Success Criteria Patterns

What Makes Good Success Criteria

Measurable

Success criteria must be objectively verifiable with specific metrics or observable outcomes.

Why: Ambiguous criteria lead to disputes about whether a feature is complete. Measurable criteria enable clear validation.

Examples:

• Specific numbers: "95% of searches return results in under 1 second"
• Observable behaviors: "Users can export reports in PDF, CSV, and Excel formats"
• Quantifiable outcomes: "Shopping cart abandonment rate decreases by 20%"

Technology-Agnostic

Focus on user-visible outcomes, not internal implementation details.

Why: Technology choices may change during implementation. Specifications should remain valid regardless of technical approach.

Good: "System supports 10,000 concurrent users" Bad: "Redis cache handles 10,000 connections"

User-Focused

Written from the perspective of what users experience, not what the system does internally.

Why: Specifications exist to capture user value. Internal metrics don't directly demonstrate user value.

Good: "Users complete checkout in under 3 minutes" Bad: "API response time under 200ms"

Verifiable

Can be tested through observation, measurement, or automated tests.

Why: If you can't verify a criterion, you can't confirm the feature is complete.

Examples:

• "All form inputs validate before submission" (testable)
• "Error messages guide users to fix issues" (observable)
• "System maintains 99.9% uptime" (measurable)

Good Examples with Explanations

E-commerce Checkout

Criterion: "Users complete checkout in under 3 minutes from cart to confirmation"

Why it's good:

• Measurable: Can time the flow
• User-focused: Describes user experience
• Technology-agnostic: No mention of implementation
• Verifiable: Can test with real users or automated flows

Search Functionality

Criterion: "95% of searches return relevant results in the first 10 items"

Why it's good:

• Measurable: Specific percentage and position
• User-focused: About result quality, not search algorithm
• Technology-agnostic: Works with any search implementation
• Verifiable: Can test with sample queries and measure relevance

Report Export

Criterion: "Users can export reports in PDF, CSV, and Excel formats with all data visible in the UI"

Why it's good:

• Measurable: Specific format list
• User-focused: About what users can do
• Technology-agnostic: No library or tool mentioned
• Verifiable: Can test each format

Bad Examples (Implementation-Focused)

API Performance

Bad Criterion: "API response time under 200ms for all endpoints"

Why it's wrong:

• Implementation detail: Exposes internal API design
• Not user-visible: Users don't directly see API response times
• Overly prescriptive: Locks in technical constraint

Convert to Good:

• "Search results appear within 1 second of user query"
• "Page transitions feel instant (no visible loading delay)"
• "Users can browse 100 products without pagination lag"

Cache Metrics

Bad Criterion: "Redis cache hit rate above 80%"

Why it's wrong:

• Technology-specific: Mentions Redis explicitly
• Internal metric: Cache hit rate isn't user-visible
• Implementation detail: Assumes caching strategy

Convert to Good:

• "Frequently accessed data loads instantly on repeat visits"
• "Dashboard loads in under 2 seconds even with 1000 items"
• "Users see updated data within 5 seconds of changes"

Framework Details

Bad Criterion: "React components render efficiently without unnecessary re-renders"

Why it's wrong:

• Technology-specific: Mentions React
• Implementation detail: Component optimization is internal
• Non-measurable: What's "efficiently"?

Convert to Good:

• "UI updates appear smooth with no visible lag when filtering 1000 items"
• "Form interactions feel responsive (under 100ms perceived delay)"
• "Page remains interactive while background data loads"

Conversion Process

Step 1: Identify the User Impact

Ask: "What user problem does this solve?" or "What user experience does this enable?"

Example:

• Bad: "Database queries optimized with indexes"
• Ask: What does this let users do?
• Good: "Search results appear in under 1 second for 99% of queries"

Step 2: Remove Technology References

Replace technology-specific terms with outcome descriptions.

Example:

• Bad: "GraphQL API supports batched queries"
• Remove: GraphQL, batched queries
• Good: "Users can load related data without multiple page refreshes"

Step 3: Add Measurable Metrics

Replace vague terms with specific numbers or observable behaviors.

Example:

• Bad: "System is fast"
• Add metrics: "System loads pages in under 2 seconds"
• Add observable: "Users see progress indicators during long operations"

Step 4: Verify User Visibility

Ask: "Can a user directly see or measure this outcome?"

Example:

• Bad: "Microservices communicate asynchronously" (not visible)
• Good: "Users receive email confirmation within 1 minute of order" (visible)