defining-stories
Guides creation of user stories and epic design documents. Use when defining new features, writing Given-When-Then criteria, creating story logs, or designing larger features that need scope definition.
When & Why to Use This Skill
This Claude skill streamlines the Agile development process by guiding the creation of comprehensive user stories and epic design documents. It helps product managers and developers define feature scopes, write precise Given-When-Then acceptance criteria, and maintain organized story logs, ensuring clear communication and efficient implementation of new features.
Use Cases
- Defining a new major feature: Creating an Epic document to outline the technical approach, scope, and high-level requirements before development begins.
- Writing precise acceptance criteria: Utilizing the Given-When-Then format to ensure user-observable behaviors and edge cases are clearly defined for developers and QA teams.
- Maintaining structured project documentation: Automatically generating timestamped story files in a standardized directory structure for better version control and audit trails.
- Standardizing verification methods: Determining the best testing approach (CLI, API, Web UI, or Mobile) for each story to ensure deliverables meet the 'Definition of Done'.
| name | defining-stories |
|---|---|
| description | Create user stories and epic design documents. Use when defining new features, writing Given-When-Then criteria, creating story logs, or designing larger features. |
Defining Stories
Epic vs Story
| Document | Purpose | When to Create |
|---|---|---|
| Epic | Design document defining scope and technical approach | Starting a larger feature |
| Story | Incremental deliverable with acceptance criteria | As needed during development |
Agile approach: Stories emerge during development. Create each story when ready to implement.
User Story Format
As a [role], I want [capability], so that [benefit].
Acceptance Criteria
- [ ] **Given** [precondition], **When** you [action], **Then** [expected result]
- Focus on user-observable behavior
- Include happy paths AND error cases
- Leave checkboxes unchecked (PO checks them)
Verification Approach
Define how criteria will be verified:
| Project Type | Options |
|---|---|
| CLI | Direct command execution |
| API | curl/httpie, API testing tools |
| Web UI | E2E tests, browser MCP tools |
| Mobile | Device/emulator, MCP tools |
| Library | Unit/integration tests |
If MCP tools or skills for testing are available, use them. If unsure, ask PO.
Story Log
File: docs/stories/<YYYYMMDDTHHMMSS>_<name>.story.md
date -u +"%Y%m%dT%H%M%S" # Generate timestamp
Use the story-template skill for structure.
Epic Documents
Directory: docs/stories/<YYYYMMDD>_<epic-name>/
File: <YYYYMMDDTHHMMSS>_<epic-name>.epic.md
Use the epic-template skill for structure.