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:
- Who is the user/actor?
- What situation triggers this need?
- What outcome do they want?
- 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.mdSpecification 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
| 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):
- Read all spec files in
specs/ - Check each against the Cardinal Rule (no code, no implementation details)
- Verify "One Sentence Without 'And'" test
- Ensure consistent naming convention
- Verify Given/When/Then format for all acceptance criteria
- 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 — 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
| Skill | Relationship |
|---|---|
autonomous-loop | Planning mode reads specs to identify implementation gaps |
acceptance-testing | Tests are derived directly from spec acceptance criteria |
reverse-engineering-specs | Generates specs from existing code (brownfield) |
prd-generation | PRD provides high-level requirements; specs detail them |
planning | Plans reference spec acceptance criteria for task definition |
test-driven-development | Red phase writes tests matching spec acceptance criteria |
writing-skills | Skills can be specified using this methodology |
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/blackVerification Gate
Before claiming specs are complete:
- VERIFY the Cardinal Rule — zero implementation details in any spec
- VERIFY every spec passes the "One Sentence Without 'And'" test
- VERIFY all acceptance criteria use Given/When/Then format
- VERIFY every spec has edge cases and data contracts
- VERIFY the story map has at least one complete SLC release slice
- 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.