specification-writing

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.

---

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

[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

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

[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

| 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

[Describe what the diagram shows]

```

┌─────────────────────────────────────────┐

│ [Component Name] │

│ ├── [field]: [type or value] │

│ └── [field]: [type or value] │

└─────────────────────────────────────────┘

│

▼ [relationship label]

┌─────────────────────────────────────────┐

│ [Component Name] │

└─────────────────────────────────────────┘

```

```

For multi-step flows:

```markdown

```

STEP 1: [Step name]

────────────────────

[What happens in this step]

STEP 2: [Step name]

────────────────────

[What happens in this step]

```

```

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

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

[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

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]

1. [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

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

```

References

Files that will be touched or consulted.

```markdown

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

```

---

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

---

When an agent reads your spec, they should:

1. Understand the problem from Motivation section
2. Know what's been explored from Research Findings
3. See the proposed direction from Design Decisions
4. Have a starting point from Implementation Plan Phase 1
5. 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.

---

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