spec-writing
Create clear, testable specifications with user stories and acceptance criteria.Triggers: spec writing, feature specification, requirements, user storiesUse when: creating new specifications or writing acceptance criteriaDO NOT use when: generating implementation tasks - use task-planning.
When & Why to Use This Skill
This Claude skill streamlines the software development lifecycle by generating clear, testable, and implementation-agnostic specifications. It excels at translating natural language feature descriptions into structured requirements, user stories, and acceptance criteria, ensuring that development teams focus on user value and measurable outcomes while avoiding technical debt caused by vague documentation.
Use Cases
- Agile Product Development: Automatically generate detailed user stories and acceptance criteria from high-level feature descriptions to populate and streamline product backlogs.
- Requirement Standardization: Transform ambiguous or informal feature requests into professional, structured specifications that follow industry-standard quality checklists.
- Success Metric Definition: Establish clear, measurable success criteria and non-functional requirements to ensure product quality and alignment with business goals.
- Cross-functional Alignment: Create a single source of truth for developers, designers, and stakeholders by documenting the 'what' and 'why' of a feature without leaking into implementation details.
| name | spec-writing |
|---|---|
| description | | |
| Triggers | spec writing, feature specification, requirements, user stories |
| Use when | creating new specifications or writing acceptance criteria |
| DO NOT use when | generating implementation tasks - use task-planning. |
| category | specification |
| tags | [speckit, specification, requirements, user-stories, acceptance-criteria] |
| - spec-kit | shared |
| - superpowers | brainstorming |
| tools | [] |
| complexity | intermediate |
| estimated_tokens | 1200 |
| progressive_loading | true |
Spec Writing
Overview
Create 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 user value and business needs rather than implementation details. Avoid specifying technology choices in requirement definitions unless strictly necessary. Ensure every requirement is testable and verifiable with measurable criteria. Limit clarification markers; make informed assumptions based on industry standards and document them 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 with no noticeable delay"
- "React components render efficiently" -> Use: "UI updates appear with no visible frame drops"
See: success-criteria-patterns module for detailed examples and conversion process
Related Skills
speckit-orchestrator: Workflow coordinationtask-planning: Converting specs to tasks
Troubleshooting
Common Issues
If specifications are too vague, use the success-criteria-patterns module to enforce measurable outcomes. If implementation details leak into specs, review against the "Core Principles" and refactor to focus on user behavior.