Spec Writing

Specification Writing

Overview

Specifications define WHAT the software should do, never HOW. This skill applies the Jobs to Be Done (JTBD) methodology to break requirements into properly scoped, testable specification files that drive autonomous implementation. Every spec produces Given/When/Then acceptance criteria free of implementation details.

This is a RIGID skill. Every phase, gate, and format rule must be followed exactly.

The Cardinal Rule

[HARD-GATE:SPEC] Specifications must NEVER contain implementation details.

Why: Implementation-free specs preserve flexibility. The implementing agent can choose the best approach for the codebase, technology, and constraints — and change course without spec updates.

Phase 1: Jobs to Be Done (JTBD)

Identify the user's or system's jobs using this format:

When [situation], I want to [motivation], so I can [expected outcome].

Examples:

• "When I upload an image, I want to extract its color palette, so I can use those colors in my design."
• "When I receive an API request, I want to validate the payload, so I can reject malformed data before processing."

Gather jobs through discovery questions: 1. Who is the user/actor? 2. What situation triggers this need? 3. What outcome do they want? 4. What happens if they cannot accomplish this?

STOP after JTBD identification — present all jobs to the user for confirmation before breaking into topics.

Phase 2: Topics of Concern

Break each job into discrete topics. Apply the "One Sentence Without 'And'" test:

Each topic becomes one specification file.

STOP after topic breakdown — confirm the list of spec files before writing them.

Phase 3: Write Specification Files

File naming convention: <int>-<descriptive-name>.md

specs/
├── 01-color-extraction.md
├── 02-palette-rendering.md
├── 03-export-formats.md
└── 04-color-accessibility.md

Specification File Template

# [Topic Name]

## Job to Be Done
When [situation], I want to [motivation], so I can [expected outcome].

## Acceptance Criteria

### [Criterion 1 Name]
- Given [precondition]
- When [action]
- Then [observable outcome]
- And [additional observable outcome]

### [Criterion 2 Name]
- Given [precondition]
- When [action]
- Then [observable outcome]

## Edge Cases
- [Describe boundary condition and expected behavior]
- [Describe error condition and expected behavior]

## Data Contracts
- Input: [Describe shape, constraints, valid ranges]
- Output: [Describe shape, guarantees, invariants]

## Non-Functional Requirements
- Performance: [measurable target, e.g., "responds within 200ms for 95th percentile"]
- Accessibility: [specific standard, e.g., "WCAG 2.1 AA"]
- Security: [specific requirement, e.g., "input sanitized against XSS"]

Acceptance Criteria Quality Rules

STOP after writing specs — run the audit checklist before proceeding to Phase 4.

Spec Audit Checklist

Phase 4: Story Map Organization

Organize specs into a story map for release planning:

CAPABILITY 1    CAPABILITY 2    CAPABILITY 3    CAPABILITY 4
─────────────   ─────────────   ─────────────   ─────────────
basic upload    auto-extract    manual arrange  export PNG
bulk upload     palette gen     templates       export SVG
drag-drop       color names     grid layout     share link
                accessibility   animation       collaborate

• Horizontal rows = candidate releases
• Top row = minimum viable release
• Each row adds capabilities across the board

SLC Release Criteria

For each horizontal slice, evaluate:

[HARD-GATE] A release must satisfy ALL three. "Simple but incomplete" is not shippable. "Complete but not lovable" is not shippable.

STOP after story map — get user confirmation on release slicing before finalizing.

Phase 5: Specs Audit Mode

When auditing existing specs (rather than writing new ones):

1. Read all spec files in specs/ 2. Check each against the Cardinal Rule (no code, no implementation details) 3. Verify "One Sentence Without 'And'" test 4. Ensure consistent naming convention 5. Verify Given/When/Then format for all acceptance criteria 6. Flag violations and auto-fix where possible

Deploy up to 100 parallel subagents via the Agent tool (with subagent_type="Explore") — one per spec file — for large spec sets.

Anti-Patterns / Common Mistakes

Anti-Rationalization Guards

• [HARD-GATE] Do NOT include ANY implementation details — no code, no tech names, no architecture
• [HARD-GATE] Do NOT skip the "One Sentence Without 'And'" test — split every compound topic
• [HARD-GATE] Do NOT accept acceptance criteria that are not in Given/When/Then format
• [HARD-GATE] Do NOT skip the audit checklist before finalizing specs
• Do NOT skip edge cases — every spec needs at least 2
• Do NOT skip data contracts — every spec needs input/output shapes
• Do NOT write specs after implementation — specs drive code, not the reverse

Integration Points

Concrete Example: Complete Spec File

# Image Color Extraction

## Job to Be Done
When I upload an image to the design tool, I want to automatically extract
its dominant colors, so I can use those colors in my design palette.

## Acceptance Criteria

### Dominant Color Extraction
- Given an uploaded image in PNG, JPG, or WebP format
- When the extraction process completes
- Then 5-10 dominant colors are returned as hex values
- And colors are ordered by prominence (most dominant first)

### Transparent Image Handling
- Given an uploaded image with transparent regions
- When the extraction process completes
- Then transparent regions are excluded from color analysis
- And at least 3 dominant colors are still returned

### Processing Feedback
- Given an image upload has started
- When extraction is in progress
- Then the user sees a progress indicator
- And extraction completes within 3 seconds for images up to 10MB

## Edge Cases
- Single-color image: returns 1 color (not an error)
- Very large image (>50MB): returns an error with size limit message
- Corrupted image file: returns an error with clear message, no crash
- Animated GIF: extracts colors from the first frame only

## Data Contracts
- Input: Image file (PNG, JPG, WebP), max 50MB
- Output: Array of 1-10 hex color strings, ordered by prominence
- Error output: Error object with code and human-readable message

## Non-Functional Requirements
- Performance: <3s for images up to 10MB, <10s for images up to 50MB
- Accessibility: Color values include WCAG contrast ratio against white/black

Verification Gate

Before claiming specs are complete:

1. VERIFY the Cardinal Rule — zero implementation details in any spec 2. VERIFY every spec passes the "One Sentence Without 'And'" test 3. VERIFY all acceptance criteria use Given/When/Then format 4. VERIFY every spec has edge cases and data contracts 5. VERIFY the story map has at least one complete SLC release slice 6. VERIFY the user has confirmed the spec set

Skill Type

Rigid — The no-implementation-details rule, JTBD structure, Given/When/Then format, and audit checklist must be followed exactly. No elements may be skipped or adapted.