# Vertical Slicing and User Stories Guide
## Creating Effective Stories for Rapid Feedback Loops

## Purpose
Guide for writing effective user stories and breaking them into vertical slices that enable rapid feedback loops and effective collaboration between humans and AI assistants.

## Key Expert Principles

**Jeff Patton** (User Story Mapping)
- Stories are placeholders for conversations, not contracts
- Think in user activities and tasks, not features
- Build a "walking skeleton" first - end-to-end but minimal

**Henrik Kniberg** (Making Sense of MVP)
- Each slice must deliver complete end-to-end value
- Skateboard → scooter → bike → car (not wheel → chassis → car)
- Build 100% of something small, learn, iterate

**Mike Cohn** (INVEST Criteria)
- **I**ndependent: Can be developed in any order
- **N**egotiable: Details can be discussed
- **V**aluable: Delivers value to user/business
- **E**stimable: Team can estimate size
- **S**mall: Completed in one sprint
- **T**estable: Clear acceptance criteria

**Ron Jeffries** (3 Cs)
- **Card**: Brief description
- **Conversation**: Ongoing discussion
- **Confirmation**: Tests that verify done

**Gojko Adzic** (Specification by Example)
- Concrete examples beat abstract specifications
- Use Given-When-Then format
- Examples become executable tests

## The Skateboard Analogy

```
❌ HORIZONTAL SLICING (Doesn't Work):
Sprint 1: Wheels → nothing usable
Sprint 2: Chassis → still nothing usable
Sprint 3: Body → still nothing usable
Sprint 4: Engine → finally works!

✓ VERTICAL SLICING (Works):
Sprint 1: Skateboard (minimal, but complete)
Sprint 2: Scooter (better, still complete)
Sprint 3: Bike (even better, complete)
Sprint 4: Motorcycle (great, complete)
```

Each increment is complete, usable, valuable, and testable.

## User Story Templates

**Standard Format:**
```
As a [type of user],
I want [some goal],
So that [some reason/benefit].
```

**Job Story Format** (better for context-driven work):
```
When [situation],
I want to [motivation],
So I can [expected outcome].
```

**Problem-Solution Format:**
```
**Problem:** [Clear statement of pain]
**Solution:** [How this addresses it]
**Value:** [Why this matters]
```

## Acceptance Criteria Patterns

**Given-When-Then:**
```
Given [initial context],
When [event occurs],
Then [expected outcome].
```

**Checklist:**
```
Acceptance Criteria:
- [ ] [Specific, testable criterion]
- [ ] [Edge case handled]
- [ ] [Error case handled]
```

## Vertical Slicing Techniques

### 1. Walking Skeleton
The smallest implementation connecting all layers.

**Example:**
```
As a developer,
I want to pull one specific Jira issue to a local file,
So that I can verify the end-to-end workflow works.

Scope:
- Hardcode one issue key
- No error handling
- Minimal authentication
- Just fetch → write file → done
```

### 2. Happy Path First
```
Story 1: Main success scenario (no errors)
Story 2: Error handling
Story 3: Edge cases
```

### 3. CRUD Slicing
```
Story 1: Read (view data)
Story 2: Create (add new data)
Story 3: Update (edit existing)
Story 4: Delete (remove)
```

### 4. Role-Based Slicing
```
Story 1: Developer role functionality
Story 2: Team lead role functionality
Story 3: Product owner role functionality
```

## Breaking Large Stories

**Process:**
1. **Identify core value**: What's the smallest thing that delivers value?
2. **Create walking skeleton**: Minimal end-to-end implementation
3. **Add happy path**: Core scenario without errors
4. **Add error handling**: One slice per error category
5. **Add edge cases**: Unusual but important scenarios
6. **Add enhancements**: Nice-to-haves that build on core

**Example:**
```
Epic: Jira Integration (too large)

Slice 1: Fetch one issue (walking skeleton)
Slice 2: Fetch multiple issues (happy path)
Slice 3: Update issue status (write operation)
Slice 4: Bidirectional sync (conflict handling)
```

## AI-Friendly Story Structure

```markdown
## Story
[As a / When / Problem format]

## Context
**Current State:** [What exists today]
**Pain Point:** [What's broken/frustrating]
**Desired State:** [What should exist]

## Acceptance Criteria
[Given-When-Then or checklist]

## Examples
**Example 1:** [Concrete scenario with inputs/outputs]
**Example 2:** [Edge case]

## Technical Notes
**Constraints:** [Technical limitations]
**Dependencies:** [What this relies on]
**Risks:** [What could go wrong]
```

## Effective AI Prompts

```
"Break this story into vertical slices that:
1. Deliver value incrementally
2. Can each be completed in 1-3 days
3. Enable fast feedback loops
4. Follow INVEST criteria"
```

```
"Identify:
1. The walking skeleton (minimal end-to-end)
2. The happy path (core scenario)
3. Error handling scenarios
4. Edge cases
Then create separate stories for each."
```

```
"Generate acceptance criteria using:
1. Given-When-Then format
2. Concrete examples
3. Edge cases and errors
Make each criterion testable and specific."
```

## Common Anti-Patterns

**❌ Horizontal Slicing:**
```
Sprint 1: Database
Sprint 2: API
Sprint 3: UI
Sprint 4: Integration
```

**✓ Vertical Slicing:**
```
Sprint 1: User can create account (all layers)
Sprint 2: User can log in (all layers)
Sprint 3: User can reset password (all layers)
```

**❌ Technical Stories:**
```
As a developer,
I want to refactor the auth code,
So that it's cleaner.
```

**✓ User Value:**
```
As a user,
I want to log in with Google,
So that I don't need another password.
```

**❌ Vague Criteria:**
```
- The feature works
- No bugs
- Fast
```

**✓ Specific Criteria:**
```
- Given 100 tasks, When I load the page, Then it renders in < 2s
- Given I create a task, When I reload, Then the task persists
- Given invalid input, When I submit, Then I see specific errors
```

## Quality Checklist

**INVEST:**
- [ ] Independent (any order)
- [ ] Negotiable (details discussable)
- [ ] Valuable (delivers user/business value)
- [ ] Estimable (team can estimate)
- [ ] Small (one sprint)
- [ ] Testable (clear criteria)

**Vertical Slice:**
- [ ] Touches all layers (UI → API → DB)
- [ ] Delivers complete functionality
- [ ] Deployable independently
- [ ] Enables fast feedback

**Clarity:**
- [ ] Title states value clearly
- [ ] Context explains current/desired state
- [ ] Acceptance criteria specific and testable
- [ ] Examples illustrate behavior
- [ ] Edge cases identified

## Complete Story Example

```markdown
# User can grep local Jira issues

## Story
As a developer working on authentication features,
I want to grep my local Jira issue files,
So that I can quickly find related issues without leaving my terminal.

## Context
**Current State:** Issues only in Jira web UI (5-10 min to search, breaks flow)
**Pain Point:** Context switching kills productivity
**Desired State:** Issues as local markdown files, grep-able like code

## Acceptance Criteria
1. Given I have pulled 50 issues locally,
   When I run `grep -r "authentication" backlog/`,
   Then I see all matching issues with file paths.

2. Given no local issues exist,
   When I run grep,
   Then I see: "No local issues. Run `imdone pull` first."

3. Given no issues match,
   When I run grep,
   Then I see no results (expected).

## Examples
```bash
$ grep -r "authentication" backlog/
backlog/current-sprint/PROJ-123.md:1:# PROJ-123: Add OAuth authentication
backlog/current-sprint/PROJ-125.md:15:Fix authentication token expiration
```

## Technical Notes
**Constraints:** Must work with standard Unix grep
**Dependencies:** Issues pulled via `imdone pull` first
**Risks:** Complex markdown format reduces grep usefulness
```

## Notes for Claude and AI Assistants

When refining user stories:

**Core Principles:**
1. **Think vertical slices** - Each story delivers complete, end-to-end value
2. **Start with walking skeleton** - Minimal implementation touching all layers
3. **Use INVEST criteria** - Independent, Negotiable, Valuable, Estimable, Small, Testable
4. **Focus on outcomes** - What value is delivered, not what code is written

**Breaking Down Stories:**
5. **Identify core value first** - What's the smallest thing that matters?
6. **Create happy path slice** - Main scenario, no error handling
7. **Add error handling slices** - One per major error category
8. **Add edge case slices** - Important but unusual scenarios

**Acceptance Criteria:**
9. **Use Given-When-Then** - Makes criteria concrete and testable
10. **Include concrete examples** - Show actual inputs/outputs
11. **Cover happy path, edge cases, errors** - Comprehensive but focused
12. **Each criterion independently verifiable** - Test separately

**Story Structure:**
13. **Use consistent templates** - Easier to parse and understand
14. **Provide context explicitly** - Current state, pain point, desired state
15. **List dependencies and constraints** - Don't assume knowledge
16. **Surface ambiguities** - Identify questions for refinement

**Quality Checks:**
17. **Can developer start immediately?** - Enough detail
18. **Clear definition of done?** - Unambiguous criteria
19. **Completable in 1-3 days?** - Not too large
20. **Delivers user value?** - Not just technical scaffolding
21. **Deployable independently?** - True vertical slice

Remember: Stories are placeholders for conversations, not detailed specifications. Clear enough to start, flexible enough to accommodate learning.

---

**Sources:**
- [User Story Mapping - Jeff Patton](https://www.jpattonassociates.com/user-story-mapping/)
- [Making Sense of MVP - Henrik Kniberg](https://blog.crisp.se/2016/01/25/henrikkniberg/making-sense-of-mvp)
- [User Stories Applied - Mike Cohn](https://www.mountaingoatsoftware.com/)
- [3 Cs - Ron Jeffries](https://ronjeffries.com/xprog/articles/expcardconversationconfirmation/)
- [Specification by Example - Gojko Adzic](https://gojko.net/books/specification-by-example/)

**Last Updated:** 2026-02-04
