# Spec Writer

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

- Skill: `jpeetz/spec-writer` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx get-skill add jpeetz/spec-writer`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jpeetz/spec-writer/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- License: MIT
- Author: JPeetz (https://skillmd.com/u/jpeetz)
- Updated: 2026-11-18
- Page: https://skillmd.com/skills/jpeetz/spec-writer

---


# 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
