Spec Writing

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