| name | spec-writer |
| description | Use when transforming plans, ideas, or feature descriptions into comprehensive implementable specifications. Triggers on tasks involving requirements engineering, spec creation, user story writing, acceptance criteria definition, or when the user asks to "write a spec", "create a specification", or "turn this plan into a spec". |
Spec Writer Skill
This skill transforms high-level plans into comprehensive, implementable specifications following the Spec-Driven Development (SDD) methodology.
When to Use This Skill
- User provides a plan, idea, or feature description and needs a spec
- User asks to "write a spec", "specify", "create requirements"
- User has a rough plan that needs to be formalized
- User needs acceptance criteria, user stories, or requirements
Specification Output Structure
Every spec you produce MUST follow this structure. Use the template at templates/spec-template.md as the output format.
Required Sections (always include):
- Project Overview — What, why, and for whom
- User Scenarios & Stories — Prioritized, independently testable
- Functional Requirements — Numbered, testable, unambiguous
- Success Criteria — Measurable, technology-agnostic
Conditional Sections (include when relevant):
- Non-Functional Requirements — Performance, security, scalability
- Key Entities & Data Model — When data is involved
- Edge Cases & Error Handling — Always for user-facing features
- Assumptions & Dependencies — When they exist
- Out of Scope — When scope boundaries matter
Process
Step 1: Parse the Plan
Extract from the user's input:
- Actors: Who uses this? (users, admins, systems, APIs)
- Actions: What do they do? (CRUD, workflows, interactions)
- Data: What data is involved? (entities, relationships, attributes)
- Constraints: What limits exist? (performance, security, platform)
- Goals: What does success look like?
Step 2: Clarify Ambiguities
For CRITICAL ambiguities only (max 5 questions):
- Prioritize: scope > security > UX > technical
- Make informed defaults for everything else
- Document defaults in the Assumptions section
Step 3: Write User Stories
Format each story as:
### User Story N - [Title] (Priority: PN)
[Plain language description]
**Why this priority**: [Value explanation]
**Independent Test**: [How to test this story alone]
**Acceptance Scenarios**:
1. **Given** [state], **When** [action], **Then** [outcome]
2. **Given** [state], **When** [action], **Then** [outcome]
Priority Guide:
- P1: Core value — the MVP. If only one story ships, it's this one.
- P2: Important — significantly enhances value
- P3: Nice-to-have — polish and delight
Step 4: Write Requirements
Format: FR-001: System MUST [specific, testable capability]
Rules:
- Every requirement is independently testable
- Use MUST for mandatory, SHOULD for recommended, MAY for optional
- No implementation details (no "using React", "via REST API", etc.)
- Every requirement traces to at least one user story
Step 5: Define Success Criteria
Format: SC-001: [Measurable, technology-agnostic metric]
Good: "Users complete signup in under 2 minutes"
Bad: "API responds in under 200ms" (too technical)
Step 6: Validate
Run through this checklist:
File Output
Save the spec to one of these locations (in priority order):
.specify/specs/[feature-name]/spec.md (if .specify/ exists)specs/[feature-name]/spec.md (if specs/ exists)[feature-name]-spec.md (fallback, project root)
Examples of Good vs Bad
Good Requirement
FR-003: System MUST allow users to reset their password via email verification within 5 minutes of request
Bad Requirement
FR-003: Implement password reset using SendGrid API with JWT tokens
Good Success Criterion
SC-002: 95% of users successfully complete their first task within 3 minutes
Bad Success Criterion
SC-002: Redis cache hit rate above 80%
Handoff Instructions
After completing the spec, inform the user:
- The spec file location
- A summary of stories and their priorities
- Any remaining NEEDS CLARIFICATION items
- Recommend: "Review the spec, then use the implementer agent to build it"
