| name | spec-writing |
| description | Create clear, testable specifications from natural language descriptions. Focus on what users need and why, not implementation details. Triggers: spec writing, feature specification, requirements documentation, user stories, acceptance criteria, success criteria, testable requirements Use when: creating new feature specifications, refining existing specifications, writing user stories and acceptance criteria, defining success criteria DO NOT use when: generating implementation tasks - use task-planning. DO NOT use when: executing implementation - use implementation-executor agent. Produces spec.md artifacts with user-focused, testable requirements. |
| category | specification |
| tags | speckit, specification, requirements, user-stories, acceptance-criteria |
| dependencies | spec-kit:shared, superpowers:brainstorming |
| tools | |
| usage_patterns | feature-specification, requirements-documentation, user-story-creation |
| complexity | intermediate |
| estimated_tokens | 1200 |
| progressive_loading | true |
| modules | success-criteria-patterns, specification-structure |
Spec Writing
Overview
Guides the creation of clear, complete, and testable specifications from natural language feature descriptions. Specifications focus on user value and business needs, avoiding implementation details.
When to Use
- Creating new feature specifications
- Refining existing specifications
- Writing user stories and acceptance criteria
- Defining success criteria
Core Principles
Focus on What, Not How
- Describe user needs and business value
- Avoid technology choices and implementation details
- Write for business stakeholders, not developers
Make It Testable
- Every requirement should be verifiable
- Use measurable criteria where possible
- Define clear acceptance scenarios
Limit Clarifications
- Maximum 3 clarification markers per spec
- Make informed guesses using industry standards
- Document assumptions explicitly
Specification Structure
Mandatory Sections
- Overview/Context: What problem does this solve?
- User Scenarios: Who uses it and how?
- Functional Requirements: What must it do?
- Success Criteria: How do we know it works?
Optional Sections
- Non-Functional Requirements (when performance/security critical)
- Edge Cases (when special handling needed)
- Dependencies (when external systems involved)
- Assumptions (when decisions made with incomplete info)
See: specification-structure module for detailed templates and guidelines
Quality Checklist
- No implementation details present
- Requirements are testable and unambiguous
- Success criteria are measurable
- User scenarios cover primary flows
- Edge cases identified
- Scope clearly bounded
Success Criteria Quick Reference
Good (User-focused, Measurable, Technology-agnostic)
- "Users complete checkout in under 3 minutes"
- "System supports 10,000 concurrent users"
- "95% of searches return results in under 1 second"
Bad (Implementation-focused, Internal metrics)
- "API response time under 200ms" → Use: "Pages load in under 2 seconds"
- "Redis cache hit rate above 80%" → Use: "Frequently accessed data loads instantly"
- "React components render efficiently" → Use: "UI updates appear smooth with no visible lag"
See: success-criteria-patterns module for detailed examples and conversion process
Related Skills
speckit-orchestrator: Workflow coordinationtask-planning: Converting specs to tasks