| name | spec-writer |
| description | Transform conversations and ideas into structured technical specifications. Outputs: User stories, acceptance criteria, technical requirements, edge cases. Use when user wants to document requirements before coding. Triggers: write spec, create user stories, document requirements, /spec
|
Spec Writer
Transform vague ideas into precise, implementable specifications that Claude Code can execute without ambiguity.
Purpose
Most AI coding failures happen because specifications are unclear. This skill extracts implicit requirements from conversations and outputs structured specs that eliminate guesswork.
Process
Phase 1: Context Extraction
Entry Check
IF user provided: problem statement + target users + success criteria
→ Proceed to Phase 2
ELSE
→ Gather missing information below (one question at a time)
Information Needed
| Item | Question | Why Required |
|---|
| Problem | "What problem are you solving?" | Defines scope boundaries |
| Users | "Who will use this?" | Shapes UX requirements |
| Success | "How will you know it works?" | Creates acceptance criteria |
| Constraints | "Any technical/business constraints?" | Prevents wasted effort |
Transition Criteria
All four items gathered + user confirmed → Phase 2
Phase 2: Requirement Analysis
Entry Check
IF Phase 1 complete:
→ Analyze and categorize requirements
ELSE
→ Return to Phase 1
Categorization Framework
FOR each requirement mentioned:
Classify as:
- MUST: Core functionality, non-negotiable
- SHOULD: Important but has workarounds
- COULD: Nice to have, time permitting
- WON'T: Explicitly out of scope (important to document)
Output: Requirements Table
| ID | Requirement | Priority | Rationale |
|---|
| R1 | [requirement] | MUST/SHOULD/COULD | [why this priority] |
Edge Case Discovery
FOR each MUST requirement:
Ask: "What happens when [edge case]?"
Common edge cases to probe:
- Empty/null inputs
- Maximum scale (1000x normal)
- Concurrent access
- Network failure
- Permission denied
- Invalid data format
Phase 3: User Story Generation
Entry Check
IF requirements table complete + edge cases documented:
→ Generate user stories
ELSE
→ Return to Phase 2
Story Format
AS A [user type]
I WANT TO [action]
SO THAT [benefit]
ACCEPTANCE CRITERIA:
- GIVEN [context]
WHEN [action]
THEN [expected result]
EDGE CASES:
- [edge case]: [expected behavior]
TECHNICAL NOTES:
- [implementation hints, if relevant]
Story Generation Rules
FOR each MUST requirement:
→ Generate 1 user story
→ Include 2-4 acceptance criteria
→ Include 1-3 edge cases
FOR each SHOULD requirement:
→ Generate 1 user story (simpler format)
→ Include 1-2 acceptance criteria
Phase 4: Technical Specification
Entry Check
IF user stories generated:
→ Ask: "Ready for technical spec, or need to adjust stories first?"
IF user confirms:
→ Generate technical specification
ELSE
→ Revise stories based on feedback
Technical Spec Structure
## Technical Specification: [Feature Name]
### Overview
[1-2 sentences describing the feature]
### Data Models
[If new data structures needed]
### API Endpoints
[If applicable]
| Method | Path | Request | Response |
|--------|------|---------|----------|
### State Changes
[What changes when this feature runs]
### Dependencies
[External services, libraries, existing code]
### Security Considerations
[Auth, validation, rate limits]
### Testing Strategy
- Unit: [what to unit test]
- Integration: [what to integration test]
- E2E: [critical user flows]
Phase 5: Output Delivery
Output Format Selection
IF user's project has existing spec format:
→ Match that format
ELSE IF user specified format preference:
→ Use requested format
ELSE
→ Use default markdown format below
Default Output Structure
# [Feature Name] Specification
## Summary
[One paragraph overview]
## Requirements
[Requirements table from Phase 2]
## User Stories
[Stories from Phase 3]
## Technical Specification
[Spec from Phase 4]
## Out of Scope
[Explicitly excluded items - prevents scope creep]
## Open Questions
[Unresolved items needing decisions]
Self-Check (Read before every response)
□ Am I gathering context or assuming?
→ Missing info = ask, never fill in
□ Am I asking one question at a time?
→ Multiple questions overwhelm users
□ Are requirements testable?
→ Vague requirements = implementation arguments later
□ Did I include edge cases?
→ Happy path only = bugs in production
□ Is the spec implementable by Claude Code?
→ Read it as if you'll code it: any ambiguity?
□ Did I document what's OUT of scope?
→ Scope creep starts with undefined boundaries
□ Are acceptance criteria specific?
→ "Works correctly" is not acceptance criteria
→ "Returns 200 with user object containing id, email" is
Integration with Other Skills
AFTER spec complete:
Suggest: "Spec ready. Next steps:"
- "Use /prd to expand into full PRD"
- "Use architect-planner to design structure"
- "Start coding with this spec as context"
