| name | story-decomposition |
| description | Break features into user-visible, testable stories using vertical slicing patterns. |
| version | 1.0.0 |
| author | Hermes Agent |
| license | MIT |
| platforms | ["linux","macos","windows"] |
| metadata | {"hermes":{"tags":["story-decomposition","agile","user-stories","acceptance-criteria","vertical-slices","invest"],"related_skills":["test-driven-development","plan","change-test-loop","writing-plans"]}} |
Story Slicing
Overview
Turn features into independently deliverable, user-visible stories. A well-sliced story is testable, demonstrable, and fits a single sprint.
Core principle: A story must deliver value to a user in a single vertical slice — not a horizontal layer (database, API, UI separately).
When to Use
- Breaking down epics or feature requests
- Planning a sprint or iteration
- Decomposing ambiguous requirements
- Reviewing existing stories that feel too large or too small
- Before writing acceptance criteria or tests
Vertical Slicing Pattern
Vertical slice = a thin end-to-end feature that touches all architectural layers.
USER
|
+---+---+
| UI | ← story lives here
+---+---+
|
+---+---+
| Logic | ← not here in isolation
+---+---+
|
+---+---+
| Data | ← and not here alone
+---+---+
A vertical slice crosses every layer to deliver one piece of user-facing value.
Good Vertical Slice
- "User can reset their password via email" — touches UI (form), logic (token generation, expiry), data (store token, update password)
Bad Horizontal Slices
- "Design the password reset database schema" — not user-visible
- "Build the password reset API endpoint" — no user value alone
- "Add a reset password button to settings page" — not functional until backend exists
How to Slice Vertically
- Identify the user — who gets value?
- Identify the outcome — what can they do afterward that they couldn't before?
- Find the thinnest path — simplest end-to-end flow that delivers that outcome
- Slice by user action, not by layer — each story is one user action through all layers
- Validate: does this make sense to demo? — if you can't demo it to a stakeholder, it's not a vertical slice
Story Sizing Guidelines
Use these as a rough calibration. Adjust based on your team's velocity.
| Size | Scope | Effort | Timeline |
|---|
| Small | One clear acceptance criterion, minimal logic change | Minutes to a few hours | Same day |
| Medium | 3–5 acceptance criteria, touches 2–3 files, possible new component | Half day to ~2 days | 1–2 days |
| Large | Complex workflow, unknowns, multiple acceptance criteria across states | 2–5 days | 3–5 days |
Small Story (Minutes – Hours)
- Change label text or button copy
- Add a simple form field with validation
- Expose an existing field in the API response
- Single-route redirect
Medium Story (Half Day – 2 Days)
- Search with filters on an existing data type
- User role-based access control for a single action
- Bulk import with validation and error reporting
- Password reset flow (request → email → reset → confirm)
Large Story (2–5 Days)
- Multi-step wizard with conditional branches
- Payment integration for one payment method
- User onboarding flow (registration → profile → first action)
- Export with format selection, progress tracking, and file delivery
When a Story Exceeds 5 Days
Slice again. A story larger than 5 days is an epic or a feature. Break it into smaller vertical slices.
Acceptance Criteria Template (Given/When/Then)
Use this structured format for all stories. It maps cleanly to both manual testing and automated tests.
Feature: [Feature Name]
Scenario: [Descriptive scenario name]
Given [precondition or context]
And [additional precondition]
When [action is performed]
And [subsequent action]
Then [expected outcome]
And [additional outcome]
Template with placeholders
Feature: <feature name>
Scenario: <what happens and under what condition>
Given <initial state / context>
And <additional precondition>
When <user action or event>
And <follow-up action>
Then <observable result>
And <additional observable result>
Examples
Good:
Feature: Password Reset
Scenario: User resets password with valid token
Given a user "alice@example.com" exists
And a valid password reset token was issued to "alice@example.com"
When the user submits the reset form with token and new password "NewP@ss1"
Then the password is updated
And a confirmation email is sent to "alice@example.com"
Good (negative case):
Feature: Password Reset
Scenario: User attempts reset with expired token
Given a user "bob@example.com" exists
And an expired password reset token for "bob@example.com"
When the user submits the reset form with the expired token
Then an error message "Token expired. Request a new reset link." is shown
And the password is NOT updated
Bad (vague, not testable):
Feature: Password Reset
Scenario: User resets password
Given the user is on the reset page
When they fill in the form
Then it works
Guidelines for Good Given/When/Then
- Given — setup. Concrete state, not "user is logged in" but "user 'alice' has session"
- When — action. One verb per scenario. Avoid "and" in When if possible
- Then — observable outcome. Describe the result, not implementation ("a 200 OK" is implementation; "the password is updated" is behavior)
- One scenario tests one behavior. If you need multiple Then clauses checking unrelated things, split the scenario
- Test happy path + error cases — each negative scenario is its own scenario
INVEST Checklist
A good story must be Independent, Negotiable, Valuable, Estimable, Small, Testable.
Run through this checklist for every story before accepting it into a sprint:
| Letter | Criterion | Check | Ask yourself |
|---|
| I | Independent | ☐ | Can this be built and released without waiting for another story? If not, can it be re-sliced? |
| N | Negotiable | ☐ | Is there room to adjust scope, implementation, or detail? Or is it a rigid spec? |
| V | Valuable | ☐ | Does a user get value from this story independently, in a single sprint? |
| E | Estimable | ☐ | Could two team members independently produce a similar estimate? Or are there too many unknowns? |
| S | Small | ☐ | Can this be completed within the sprint (ideally < 3 days)? If not, slice it. |
| T | Testable | ☐ | Are acceptance criteria written as clear pass/fail conditions? Could QA run them without asking for clarification? |
INVEST in Practice
Independent — Stories should be ordered by priority. If story B depends on story A, consider:
- Making them the same story
- Re-slicing so each delivers value independently
- Documenting the dependency explicitly if unavoidable
Negotiable — A story is negotiable if the team can discuss implementation details. Red flags:
- "Must use technology X"
- Detailed UI mockup with no room for change
- Requirements that specify implementation rather than behavior
Valuable — Value is from the user's perspective, not the developer's:
- "Add a
users_count field to the API response" (no user value)
- "Show admin how many users are registered on the dashboard" (user value for admin)
Estimable — A story is estimable when the team understands the scope. If estimates vary wildly:
- Run a spike to resolve unknowns
- Slice smaller to reduce uncertainty
- Add a timeboxed investigation story
Small — Small means completable. If a story wouldn't fit on a 3×5 index card, it's probably too big.
Testable — A story needs clear pass/fail. If the acceptance criteria can't be executed as automated or manual tests, rewrite them. "UI looks good" is not testable. "The success message appears below the form in green text" is testable.
Common Slicing Anti-Patterns
| Anti-Pattern | Problem | Fix |
|---|
| Horizontal slice (API layer in one story, UI in another) | Nothing demo-able until both done | Combine into one vertical slice per user action |
| Technical story (set up CI, refactor database, add logging) | No user value | Wrap in a user-facing story, or make it a chore (not a story) |
| Fat story (everything about users: register, login, profile, reset) | Can't finish in a sprint | Slice by user action — one action per story |
| Tiny story (change button color, update error message) | No real value, overhead > benefit | Batch related tiny changes into one story |
| Zombie story (no defined acceptance criteria) | Can't test, can't demo, can't estimate | Add Given/When/Then criteria or reject the story |
| Implementation story ("Add a database index on email") | Doesn't describe user behavior | Reframe: "User can sign up without timeout" with performance acceptance criteria |
Verification Checklist
Before marking a story as ready:
