k8 User Story

Use this when you need to write, review, critique, or split user stories with testable acceptance criteria that engineers can build from and QA can verify.

---

What it is

A user story is a short description of a feature from the perspective of someone who wants it. Good stories are the contract between product, design, and engineering. They define what to build, for whom, and how to know it's done.

In AI-assisted development, stories become even more important. When an agent executes a story, the acceptance criteria are the specification. Vague criteria produce vague code. Testable criteria produce testable software.

---

The INVEST standard

Every story must be:

Criterion	What it means
Independent	Can be built alone, no dependencies on unfinished stories
Negotiable	Written so anyone on the team can question and refine it
Valuable	Clear value for the user or the business (ideally both)
Estimable	Enough detail for the team to estimate effort
Small	Completable in 1-3 days, addressing a single vertically sliced feature
Testable	Acceptance criteria that can be verified empirically

If a story fails any of these, it's not ready for iteration.

---

Story structure

Title

A brief description of what the user can do.

Description

Use the standard format:

As a (user persona), I want to be able to (action), so that (purpose/value).

Acceptance criteria (Gherkin format)

Written in Given/When/Then so they translate directly into automated tests.

Each acceptance criterion must:

• Refer to a user interaction (not implementation details)
• Cover success paths, error paths, and edge cases
• Be usable as test criteria
• Be numbered starting from 1

Technical details

Bullet points for engineers and designers: tech stack notes, unknowns, constraints, API details.

Links to designs

Figma links, wireframes, or prototype references.

Out of scope

Explicitly state what is NOT included. Reference related stories that cover excluded items.

Added context

Environment notes, dependencies, or implementation considerations.

---

Gherkin language rules

Given

Describes the initial context. The "scene" of the scenario. Typically past tense. Puts the system in a known state before user interaction.

When

Describes an event or action. A person interacting with the system or an event triggered by another system.

Then

Describes the expected outcome. Something observable (UI change, message, report), not something internal (database record).

And / But

Use And or But to chain multiple Given, When, or Then steps for readability.

Given I am logged in
And I have items in my cart
When I click "Checkout"
Then I see the order summary
And the total reflects all items plus tax
But I do not see items I removed earlier

---

Vertical slicing

Stories are sliced vertically. Each slice delivers end-to-end value through all layers of the stack.

Good split (vertical):

• "User can create an account with email"
• "User can create an account with Google SSO"

Bad split (horizontal):

• "Build the registration API endpoint"
• "Build the registration form UI"

Horizontal splits create dependencies and block independent delivery.

---

AI-assisted story writing workflow

1. You describe the feature with what the user needs to do and why
2. The agent drafts the story following the structure above, with Gherkin acceptance criteria
3. You review and refine by challenging criteria, adding missing edge cases, adjusting scope
4. Iterate as the agent refines based on your feedback
5. The agent splits if needed when the story is too large

What agents catch that humans miss

• Error scenarios that enumerate what can go wrong
• Edge cases like empty states, max lengths, concurrent users, offline behavior
• Missing Given conditions with prerequisite state that needs setup
• Inconsistent terminology where the same concept has different names across stories

---

Iterative story writer prompt

You are an experienced agile product owner. Your goal is to help me write user stories.

Pay particular attention to engineer and designer needs. Use information from any previous stories in the conversation to inform each new story.

## Standards
Every story must meet the INVEST criteria:
a) Independent — can be built alone with no dependencies on other unfinished features
b) Negotiable — written so anyone on the team can question it
c) Valuable — clear value for the user or the business (ideally both)
d) Estimable — enough detail for the team to estimate effort
e) Small — completable in 1-3 days, addressing a single vertically sliced feature
f) Testable — acceptance criteria written in Gherkin format that can be verified empirically

## Process

**Step 1.** Ask me what story I need to write. Do nothing else until I provide my answer.

**Step 2.** Based on my input, generate two sections:
  a) A revised, clarified description of what the story should cover
  b) Questions — ask any relevant questions to fill gaps. Explain why each question matters.

**Step 3.** We iterate: I answer your questions, you update the story description. Repeat until you have enough information. If I say I don't want to answer more questions, skip to Step 4.

**Step 4.** If the story should be split into multiple stories, split it. Then write each story using the structure below.

## Story structure

**Title**
A brief description of the user story.

**Description**
As a [user persona], I want to be able to [action], so that [purpose].

**Acceptance Criteria**
Written in Gherkin format (Given/When/Then). Requirements:
- Cover all user interactions needed to fulfill the story
- Cover success paths, error paths, and edge cases
- Number all scenarios starting from 1
- Each criterion must refer to a user interaction — no criteria about style consistency
- Must be usable as test criteria

**Technical Details**
- Bullet points for engineers, designers, or data scientists
- Include unknowns

**Links to Designs**
- Placeholder for design links

**Out of Scope**
- What is NOT included in this story
- Reference related stories that cover excluded items

**Added Context**
- Environment notes, dependencies, or implementation considerations

## Gherkin rules

**Given** — initial context / system state (past tense, no user interaction)
**When** — an event or user action
**Then** — expected observable outcome (UI, message, report — not database internals)
**And / But** — chain multiple steps for readability

Use And/But instead of repeating Given/When/Then for successive steps.

---

Story splitting prompt

For when a story is too large:

This user story is too large to complete in 1-3 days. Help me split it into smaller, vertically sliced stories that each deliver end-to-end value independently.

Story:
[Paste the full story here]

For each proposed split:
1. Write the story title and a one-line description
2. Explain what slice of value it delivers
3. Note any dependencies between the split stories
4. Confirm each split meets INVEST criteria

Prefer splitting by user workflow step or by scenario, not by technical layer (don't split into "frontend" and "backend" stories).

---

Examples

Example 1: Successful account registration

Title: Successfully Register for an Account

Description: As a new user, I want to create an account so that I can start using the platform.

Acceptance Criteria:

Scenario 1: Successful sign-up

GIVEN I am on the sign-up page AND I enter valid values for all required fields AND user creation is going to succeed

WHEN I click on the "Sign Up" button

THEN I am redirected to the home page

Technical Details:

• Authentication provider: (e.g., Okta, Auth0, Firebase)
• Required fields and validation rules:
  • First Name: 2-32 characters, alpha only
  • Last Name: 2-32 characters, alpha only
  • Email Address: valid email format
  • Password: (specify requirements)
  • Password Confirmation: must match password

Out of Scope:

• Error scenarios for invalid input (see Example 2)
• Social login (Google, GitHub, etc.)

Example 2: Failed registration with invalid input

Title: Failed Account Registration Due to Invalid Field Entries

Description: As a user, when I enter invalid data while registering, I want to see clear error messages so that I can fix my input and complete registration.

Acceptance Criteria:

Scenario 1: Missing a required field

GIVEN I am on the sign-up page AND I enter valid values for all required fields except I leave one required field empty

WHEN I click on the "Sign Up" button

THEN I see a red border around the empty field AND I see red text underneath: "This field is required"

Scenario 2: Invalid field value

GIVEN I am on the sign-up page AND I enter valid values for all required fields except I enter an invalid value for one or more fields

WHEN I click on the "Sign Up" button

THEN I see a red border around each field with an invalid value AND I see the appropriate validation error message in red text underneath each invalid field

Technical Details:

• Client-side validation must run before the API call
• Validation error messages:
  • First/Last Name too short: "Must be at least 2 characters"
  • First/Last Name too long: "Must be 32 characters or fewer"
  • Email invalid: "Enter a valid email address"
  • Password mismatch: "Passwords do not match"

Out of Scope:

• Server-side errors (e.g., network failure, server downtime)
• Duplicate email handling

---

Story readiness checklist

• Title is concise and describes what the user can do
• Description follows "As a / I want / So that" format
• Acceptance criteria are in Gherkin format (Given/When/Then)
• All success paths are covered
• Error and edge cases are covered (or explicitly out of scope with a reference)
• Technical details include what engineers need to know
• Out of scope is explicit
• Story is small enough to complete in 1-3 days
• A designer has reviewed (or doesn't need to)
• An engineer has confirmed it's estimable

---

Common pitfalls

Pitfall	Fix
Vague AC: "System handles errors gracefully"	Specify which errors and what "gracefully" means
Implementation as AC: "Use Redis for caching"	Describe the behavior, not the implementation
Stories that are tasks, not user value	"Set up migration" is a task. Wrap tasks inside stories.
Missing error paths	Add at least one error scenario per story
Story too big (> 3 days)	Split into vertical slices
No "so that" in description	Add the value statement
AC about styling	"Consistent with design system" isn't testable by a user
Writing in isolation	Stories are best written collaboratively (PM + Design + Eng)