spec-writer v1.0.0A

Immutable. This exact content is served forever at /api/v1/blob/0fd6e14d636b0365.

---
name: spec-writer
description: >
  Use this skill when a vague feature request, ticket, PRD fragment, or rough idea
  needs to be turned into a structured specification, technical plan, and ordered
  task breakdown for AI coding agents. Generates all three output sections
  immediately, then flags every implicit decision as an inline [ASSUMPTION: ...]
  marker with an impact rating and correction guidance — no back-and-forth
  questions needed before drafting. Primary keywords: spec-driven development
  SDD, feature specification generation, technical planning, task breakdown,
  assumption flagging, acceptance criteria Given When Then, requirements
  engineering, feature request refinement, specification writing agent,
  plan-first development. For all major agentic platforms.
version: 1.0.0
author: JPeetz (based on spec-writer by dannwaneri)
license: MIT
compatibility: >
  Cross-platform: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Windsurf,
  Gemini CLI, OpenClaw, Hermes Agent, OpenCode, and any SKILL.md-compatible agent.
tags:
  - spec-writing
  - technical-planning
  - task-breakdown
  - requirements-engineering
  - spec-driven-development
  - sdd
  - feature-specification
  - assumption-tracking
  - acceptance-criteria
  - plan-first
  - documentation
platforms:
  - claude-code
  - codex
  - opencode
  - cursor
  - gemini-cli
  - openclaw
  - hermes-agent
  - windsurf
  - copilot
---

# Spec Writer

Turns a vague feature request into a structured spec, technical plan, and task breakdown — ready for any coding agent to implement without guessing.

---

## Overview

AI coding agents don't fail because the model is weak. They fail because the instructions are ambiguous. This skill closes that gap **before** the agent starts.

Given any feature description — a sentence, a ticket, a PRD fragment, a rough idea — spec-writer produces three deliverables in a single output:

1. **A Spec** — functional, technology-agnostic. What the feature does, who uses it, what must be true, what can go wrong, and binary acceptance criteria in Given/When/Then format.
2. **A Plan** — technical and concrete. Architecture decisions, data model changes, API contracts, testing strategy, security constraints.
3. **A Task breakdown** — ordered, self-contained tasks. Each completable in a single agent session. Each with its own acceptance criteria.

The key methodology: **generate first, flag assumptions inline**. Instead of asking clarifying questions before drafting, the skill produces a complete output and marks every decision made without user input as `[ASSUMPTION: ...]` — impact-rated, with guidance on when to correct it.

---

## When to Use

- A stakeholder or user sends a vague feature request ("add export", "build a dashboard", "let users invite teammates")
- You have a Jira ticket, Linear issue, or GitHub issue that says *what* but not *how*, and needs decomposing into agent-ready work
- You need to validate scope and surface hidden assumptions before implementation starts
- You're handing work to another agent or developer and want to eliminate ambiguity
- You want acceptance criteria that are **binary pass/fail**, not "works correctly"
- You need a plan-first methodology for Spec Driven Development (SDD)

Do **not** use this skill when:
- The requirements are already a complete, unambiguous spec with acceptance criteria
- You need a quick one-line answer rather than a structured document
- You're asking a question rather than requesting a feature

---

## How to Invoke

```
/spec-writer [feature description]
```

Pass anything — a feature description, a ticket, a PRD fragment, a rough idea:

```
/spec-writer Add password reset via email
/spec-writer Build an admin dashboard showing daily active users
/spec-writer Let users invite teammates to their workspace
/spec-writer Add rate limiting to the public API
```

The skill produces a complete spec, plan, and task breakdown in one shot. No intermediate questions.

---

## Output Format

The output is a single document with three sections, each clearly delimited:

### Spec Section

The Spec section contains:

- **Purpose** — one or two sentences describing the feature's goal
- **Use case(s)** — who uses this feature and what they accomplish
- **Functional requirements** — what the system must do (numbered)
- **Non-functional requirements** — performance, security, compliance constraints
- **Acceptance criteria** — binary Given/When/Then scenarios
- **Edge cases** — what happens at boundaries, with empty states, with errors

### Plan Section

The Plan section contains:

- **Architecture decisions** — components, interactions, data flow
- **Data model changes** — new/modified entities, fields, relationships
- **API contracts** — endpoints, methods, request/response shapes
- **UI changes** — components, states, navigation flow
- **Testing strategy** — unit, integration, E2E coverage requirements
- **Security & performance constraints** — auth, rate limiting, caching, SLAs

### Task Breakdown Section

The Task breakdown section contains:

- A numbered list of **ordered, self-contained tasks**, each with:
  - **Dependencies** — which tasks must complete first
  - **Acceptance criteria** — binary pass/fail conditions unique to that task
  - **Estimated complexity** — (small / medium / large)
- No task says "implement the feature" — every task is independently verifiable

---

## Assumption Markers

Every decision the skill makes without explicit user input is marked inline with an `[ASSUMPTION: ...]` annotation:

```
When the export contains more than 1,000 rows
  [ASSUMPTION: async for large exports — Impact: HIGH]
Then the export is generated asynchronously and the user is notified by email
```

At the end of the output, all assumptions are collected into a prioritized summary:

```
## Assumptions to Review
1. Async generation for exports over 1,000 rows — Impact: HIGH
   Correct this if: your order volumes are low and synchronous is fine
2. Date range filter is required — Impact: MEDIUM
   Correct this if: the first version should export all orders with no filtering
```

### Assumption Impact Levels

| Impact | Meaning |
|--------|---------|
| **HIGH** | Changing this assumption could significantly alter the architecture or effort |
| **MEDIUM** | Changing this assumption would affect the design but not the overall approach |
| **LOW** | Changing this assumption is a minor adjustment with no architectural impact |

---

## Common Pitfalls

1. **Over-specifying technology in the Spec section.** The Spec must remain technology-agnostic. Framework choices, database decisions, and library selections belong in the Plan section only.
2. **Acceptance criteria that aren't binary.** "Works correctly" is not a criterion. "Returns 401 when unauthenticated" is. Every criterion must be testable as pass/fail.
3. **Tasks that are too large.** If a task's acceptance criteria read like a mini-spec, break it down further. Every task should be completable in a single agent session.
4. **Missing edge cases.** Always include empty states, error states, boundary conditions (pagination limits, max file size, timeout duration), and concurrent access.
5. **Skipping the assumptions review.** The generated assumptions are a feature, not a bug. Always explicitly review and either confirm or override each HIGH/MEDIUM assumption before handing the output to an implementer.
6. **Mixing spec with plan details.** If an acceptance criterion mentions a specific library or framework, it belongs in the Plan. Keep the Spec pure functional requirements.
7. **No non-functional requirements.** Storage limits, latency targets, concurrency expectations, and accessibility requirements are often assumed but must be explicit.

---

## Verification

After generating the output, verify the following before considering it complete:

- [ ] **Every [ASSUMPTION] marker is impact-rated** — HIGH, MEDIUM, or LOW — with correction guidance
- [ ] **Assumptions are collected** into a single summary section at the end
- [ ] **Spec is technology-agnostic** — no framework, library, or infrastructure choices in functional requirements or acceptance criteria
- [ ] **Acceptance criteria are binary** — every scenario is a clear Given/When/Then that can pass or fail
- [ ] **Plan contains concrete decisions** — architecture, data model, API contracts, testing strategy
- [ ] **Tasks are self-contained** — each has unique acceptance criteria and clear dependencies
- [ ] **No task says "implement the feature"** — the largest task should be implementable in a single agent session
- [ ] **Edge cases are covered** — empty states, error states, boundary conditions, concurrent access
- [ ] **Non-functional requirements are present** — performance, security, storage, latency