Specification Writing

Follow writing-voice for prose sections.

A specification gives an agent (or human) the context they need to implement a feature autonomously. The goal is NOT to describe everything exhaustively; it's to provide enough initial context that the implementer can do their own research and make informed decisions.

Note: This guide uses
[PLACEHOLDER]
markers for content you must fill in. Code blocks show templates; replace all bracketed content with your feature's details.

The Core Philosophy

Specs should:

Provide context, not instructions: Give the "why" and "what", let the implementer figure out "how"
Document research, not conclusions: Show what was explored, what exists, what doesn't
Leave questions open: The Open Questions section is a feature, not a bug
Enable autonomous implementation: An agent reading this should spawn sub-agents to verify and extend

A good spec is a launching pad, not a script to follow.

Document Structure

Header (Required)

markdown

# [Feature Name]

**Date**: [YYYY-MM-DD]
**Status**: Draft | In Progress | Implemented
**Author**: [Name or AI-assisted]
**Branch**: [optional: feat/feature-name if work has started]

Overview

One paragraph max. Describe what the feature does. Don't sell it.

markdown

## Overview

[One to two sentences describing what this feature adds or changes and what it enables. Be specific about the capability, not vague about benefits.]

Motivation

Structure as Current State → Problems → Desired State.

markdown

## Motivation

### Current State

[Show actual code or configuration demonstrating how things work TODAY. Use real code blocks, not prose descriptions.]

This creates problems:

1. **[Problem Title]**: [Specific explanation of what breaks or is painful]
2. **[Problem Title]**: [Specific explanation of what breaks or is painful]

### Desired State

[Brief description of what the target looks like. Can include a code snippet showing the ideal API or structure.]

Research Findings

This is where specs shine. Document what you FOUND, not what you assumed.

markdown

## Research Findings

### [Topic Researched]

[Description of what you investigated and methodology]

| [Category]    | [Dimension 1]  | [Dimension 2]    |
| ------------- | -------------- | ---------------- |
| [Project/Lib] | [What they do] | [Their approach] |
| [Project/Lib] | [What they do] | [Their approach] |

**Key finding**: [Your main discovery—could be that no standard exists, or that everyone does X]

**Implication**: [What this means for your design decisions]

Include:

What similar projects do (comparison tables)
What you searched for but didn't find ("No Established Pattern Exists")
Links or references to documentation you consulted

Design Decisions

Use a table for traceability. Every decision should have a rationale.

markdown

## Design Decisions

| Decision            | Choice           | Rationale                       |
| ------------------- | ---------------- | ------------------------------- |
| [Decision point]    | [What you chose] | [Why this over alternatives]    |
| [Decision point]    | [What you chose] | [Why this over alternatives]    |
| [Deferred decision] | Deferred         | [Why it's out of scope for now] |

Architecture

Diagrams over prose. Show relationships visually with ASCII art.

markdown

## Architecture

[Describe what the diagram shows]

┌─────────────────────────────────────────┐ │ [Component Name] │ │ ├── [field]: [type or value] │ │ └── [field]: [type or value] │ └─────────────────────────────────────────┘ │ ▼ [relationship label] ┌─────────────────────────────────────────┐ │ [Component Name] │ └─────────────────────────────────────────┘

undefined

For multi-step flows:

markdown

undefined

STEP 1: [Step name] ──────────────────── [What happens in this step]

STEP 2: [Step name] ──────────────────── [What happens in this step]

undefined

Implementation Plan

Break into phases. Use checkboxes for tracking. Phase 1 should be detailed; later phases can be rougher (the implementer will flesh them out).

markdown

## Implementation Plan

### Phase 1: [Phase Name]

- [ ] **1.1** [Specific, atomic task]
- [ ] **1.2** [Specific, atomic task]
- [ ] **1.3** [Specific, atomic task]

### Phase 2: [Phase Name]

- [ ] **2.1** [Higher-level task—implementer will break down]
- [ ] **2.2** [Higher-level task]

Edge Cases

List scenarios that might break assumptions or need special handling.

markdown

## Edge Cases

### [Scenario Name]

1. [Initial condition]
2. [What happens]
3. [Expected outcome or "See Open Questions"]

### [Scenario Name]

1. [Initial condition]
2. [What happens]
3. [Expected outcome]

Open Questions

This section signals "you decide this" to the implementer. Include your recommendation but don't close the question.

markdown

## Open Questions

1. **[Question about an unresolved design decision]**
   - Options: (a) [Option A], (b) [Option B], (c) [Option C]
   - **Recommendation**: [Your suggestion and why, but explicitly leave it open]

2. **[Another unresolved question]**
   - [Context about why this is uncertain]
   - **Recommendation**: [Suggestion or "Defer until X"]

Success Criteria

How do we know this is done? Checkboxes for verification.

markdown

## Success Criteria

- [ ] [Specific, verifiable outcome]
- [ ] [Specific, verifiable outcome]
- [ ] [Tests pass / build succeeds / docs updated]

References

Files that will be touched or consulted.

markdown

## References

- `[path/to/file.ts]` - [Why this file is relevant]
- `[path/to/pattern.ts]` - [Pattern to follow or reference]

Good vs Bad Specs

Good Spec Characteristics

Research is documented: Shows what was explored, not just conclusions
Decisions have rationale: Every choice has a "why" in a table
Questions are left open: Implementer has room to decide
Code shows current state: Not described abstractly
Architecture is visual: ASCII diagrams over prose
Phases are actionable: Checkboxes that can be tracked

Bad Spec Characteristics

Prescriptive step-by-step: Reads like a tutorial, no room for autonomy
Assumes without research: "We'll use X" without exploring alternatives
Closes all questions: No Open Questions section
Abstract descriptions: "The system will handle Y" without showing code
Wall of prose: No tables, no diagrams, no structure

Writing for Agent Implementers

When an agent reads your spec, they should:

Understand the problem from Motivation section
Know what's been explored from Research Findings
See the proposed direction from Design Decisions
Have a starting point from Implementation Plan Phase 1
Know what to investigate further from Open Questions

The agent will then:

Spawn sub-agents to verify your research
Explore the Open Questions you left
Flesh out later phases of the implementation plan
Make decisions where you left room

If your spec is too prescriptive, the agent will blindly follow it. If it's too vague, the agent will flounder. The sweet spot is: enough context to start, enough openness to own the implementation.

Quick Reference Checklist

markdown

- [ ] Header (Date, Status, Author)
- [ ] Overview (1-2 sentences)
- [ ] Motivation
  - [ ] Current State (with code)
  - [ ] Problems (numbered)
  - [ ] Desired State
- [ ] Research Findings
  - [ ] Comparison tables
  - [ ] Key findings
  - [ ] Implications
- [ ] Design Decisions (table with rationale)
- [ ] Architecture (ASCII diagrams)
- [ ] Implementation Plan (phased checkboxes)
- [ ] Edge Cases
- [ ] Open Questions (with recommendations)
- [ ] Success Criteria
- [ ] References

Not every spec needs every section. A small feature might skip Research Findings. A migration spec might focus heavily on Edge Cases. Use judgment.

specification-writing

NPX Install

Tags

SKILL.md Content

Specification Writing

The Core Philosophy

Document Structure

Header (Required)

Overview

Motivation

Research Findings

Design Decisions

Architecture

Implementation Plan

Edge Cases

Open Questions

Success Criteria

References

Good vs Bad Specs

Good Spec Characteristics

Bad Spec Characteristics

Writing for Agent Implementers

Quick Reference Checklist