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

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