spec-writing

What this skill does

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

| Forbidden | Allowed |
|-----------|---------|
| Code blocks or snippets | Behavioral descriptions |
| Variable names or function signatures | Observable outcomes |
| Technology choices ("use React", "use PostgreSQL") | Capability requirements ("renders in browser", "persists data") |
| Algorithm suggestions ("use K-means clustering") | Success criteria ("extracts 5-10 dominant colors") |
| Architecture patterns ("use MVC") | User-facing behaviors |
| Library references ("use Zod for validation") | Validation requirements ("rejects malformed input") |

**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:**

| Test | Result | Action |
|------|--------|--------|
| "This spec covers color extraction." | PASS | Single topic — one spec file |
| "This spec covers color extraction and palette rendering." | FAIL | Two topics — split into two spec files |
| "This spec covers user authentication and session management." | FAIL | Split into two specs |
| "This spec covers input validation for the registration form." | PASS | Single topic — one spec file |

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

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

| Rule | Good Example | Bad Example |
|------|-------------|-------------|
| Observable behavioral outcome | "Extracts 5-10 dominant colors from any image" | "Use K-means clustering with k=8" |
| Testable | "Color data persists across sessions" | "Store in PostgreSQL JSONB column" |
| Specific and measurable | "Palette changes appear within 500ms" | "Use WebSocket for real-time updates" |
| Independent (stands alone) | "Palette renders when image loads" | "Implement with React useEffect hook" |
| Implementation-free | "Passwords cannot be recovered from stored data" | "Use bcrypt with 12 salt rounds" |

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

### Spec Audit Checklist

| # | Check | Pass Criteria |
|---|-------|--------------|
| 1 | No implementation details | Zero code, function names, or tech choices |
| 2 | One Sentence Without 'And' test | Each spec covers exactly one topic |
| 3 | All criteria are Given/When/Then | No free-form prose criteria |
| 4 | All criteria are testable | Each can be verified by a test |
| 5 | Edge cases documented | At least 2 per spec |
| 6 | Data contracts defined | Input and output shapes specified |
| 7 | Consistent naming | `<int>-<descriptive-name>.md` format |

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

| Criterion | Question | Standard |
|-----------|----------|----------|
| **Simple** | Can it ship fast with narrow scope? | Weeks, not months |
| **Lovable** | Will people actually want to use it? | Delightful, not just functional |
| **Complete** | Does it fully accomplish a job? | End-to-end, not half-done |

**[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

| Mistake | Why It Is Wrong | What To Do Instead |
|---------|----------------|-------------------|
| Including code snippets in specs | Locks implementation approach | Describe behavior, not mechanism |
| Naming technologies ("use Redis") | Prevents better alternatives | Describe capability ("caches results") |
| Combining topics with "and" | Spec too broad, hard to implement/test | Split into separate spec files |
| Vague acceptance criteria ("works well") | Cannot write a test for it | Specific measurable outcome |
| Missing edge cases | Bugs in boundary conditions | Document at least 2 edge cases per spec |
| Skipping data contracts | Input/output ambiguity | Always define shapes and constraints |
| Writing specs after code | Specs justify code instead of driving it | Specs come BEFORE implementation |
| Acceptance criteria that describe UI layout | Implementation detail | Describe what the user can accomplish |

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