User Stories
You have prioritized requirements in requirements.md. The next step is converting them into user stories with acceptance criteria. This is not bureaucratic overhead — user stories with acceptance criteria become the contract for development. Every acceptance criterion becomes a test case in Phase 3. Every scope boundary prevents over-engineering.
The format is simple: As a [role], I want [capability] so that [business value]. Each story gets acceptance criteria — specific, testable conditions that define done. If you cannot write testable criteria, the requirement is too vague.
Only turn user-facing functionality into stories. Tooling, testing methodology, infrastructure setup, and team practices (e.g. "we mandate TDD") are non-functional requirements — they belong in requirements.md under a Non-Functional Requirements section, not as user stories. If you convert a methodology mandate into a story, it becomes a fake "unit" in the backlog and derails Phase 2 and 3.
The INVEST criteria apply to AI-assisted development even more than traditional: Independent (one Claude session = one story), Negotiable (details can change), Valuable (delivers end-user value), Estimable (scope is clear enough to estimate), Small (fits in one session's context window), Testable (has acceptance criteria that can be verified).
| Quality | Bad Example | Good Example |
|---|---|---|
| Testable | "The API should handle comments well" | "POST /api/tasks/:id/comments returns 201 with the created comment" |
| Scoped | "Add comments" | "Add comment creation endpoint: POST /api/tasks/:id/comments with author and text fields" |
| Independent | "Add comments and update the UI" | "Add comment creation endpoint" (separate story for UI) |
| Valuable | "Refactor the comment storage" | "As a team member, I can leave comments on tasks so context isn't lost in Slack" |
Field experience shows that user stories with acceptance criteria become the contract for development. In Phase 3, Claude generates tests from acceptance criteria FIRST, then implements to pass them. If the criteria are vague, both outputs suffer.
You have requirements/requirements.md with prioritized MUST/SHOULD/COULD items from the previous experiment.
Step 1 — Generate user stories: Ask Claude to convert the prioritized requirements into user stories with acceptance criteria.
Tell Claude:
Read the prioritized requirements in requirements/requirements.md.
Convert user-facing functional requirements into user stories with acceptance criteria.
For each story:
- Use the format: As a [role], I want [capability] so that [value]
- Write 3-5 specific, testable acceptance criteria per story
- Group stories by the priority categories (MUST/SHOULD/COULD)
- Each deliverable named in a requirement becomes its own story. Never mark a deliverable 'not included' or 'separate session' — if it is in the requirement, write a sibling story and link it with a dependency note.
Do NOT create stories for non-functional items — tooling setup,
test infrastructure, methodology mandates (e.g. "we use TDD"),
or team practices. Record those in requirements/requirements.md
under a "Non-Functional Requirements" section instead. They are
constraints on HOW we build, not user-facing features.
Write to requirements/stories.mdObserve: Claude produces user stories organized by priority.
Open requirements/stories.md and read through the stories. Are the acceptance criteria specific and testable? Could you hand any single story to a developer (or Claude) and get a correct implementation? Watch for vague language like "should handle errors gracefully" — that needs to become something you can actually test.
Step 2 — Validate story quality: Ask Claude to self-review and tighten any vague criteria.
Tell Claude:
Review the stories you just wrote in requirements/stories.md.
For each story, verify:
1. Every acceptance criterion is specific and testable (no 'gracefully', 'properly', 'correctly')
2. Scope boundaries are explicit (what this story does NOT include)
3. No story combines two independent user behaviors
4. No 'Not included' item is actually a deliverable from the source requirement — if it is, write a sibling story instead.
Fix any issues you find.Observe: Claude self-reviews and typically tightens 2-3 criteria. This review step catches vagueness before it propagates to design and implementation.
You now have user stories that serve double duty: they guide implementation in Phase 3 AND generate tests before that implementation begins. The acceptance criteria are the bridge between what stakeholders want and what code does.