User Story Creation

User Story Creation

Quick Actions & Routing

Command Integration

The /re:create-stories command guides user story creation in GitHub Projects. This skill provides the methodology for writing effective stories—including INVEST criteria validation and splitting techniques for oversized stories. Load this skill for deeper understanding of story creation concepts or when you need guidance beyond what the command provides.

Overview

User story creation transforms epics into specific, actionable requirements that describe functionality from a user's perspective. Well-written user stories follow the INVEST criteria and provide clear value while remaining small enough to be completed in a single iteration. This skill guides the process of breaking down epics into high-quality user stories.

Purpose

User stories serve as the detailed requirements layer:

• Above: Epics (major capabilities)
• Stories: Specific user-facing functionality
• Below: Tasks (implementation steps)

Ensure user stories:

• Describe functionality from user perspective
• Deliver independent, testable value
• Fit within a single iteration/sprint
• Enable detailed estimation and planning
• Facilitate conversation and refinement

Prerequisite

Epic must exist before creating stories. If no epic exists, use the epic-identification skill first.

User Story Format

Standard Template

As a [user type/persona],
I want [goal/desire],
So that [benefit/value].

Include these components:

• User type: Specify WHO wants this (specific role or persona)
• Goal: Define WHAT they want to do (capability or action)
• Benefit: State WHY it matters (value or outcome)

Example Stories

Good:

As a marketing manager,
I want to filter campaign data by date range,
So that I can analyze performance for specific time periods.

Poor:

As a user,  (too vague—which user?)
I want to see data,  (too vague—what data? how?)
So that I can use the app.  (no specific benefit)

When to Deviate from Template

Apply these guidelines:

• Use the template when it clarifies value and perspective
• Deviate when it adds unnecessary words
• Consider alternative: Simple title + detailed description

Alternative format:

• Title: "Filter campaigns by date range"
• Description: Detailed explanation of functionality and value

INVEST Criteria (Quick Reference)

Validate every user story against these criteria. For detailed guidance with examples, see references/invest-criteria.md.

Story Creation Process

Step 1: Review the Epic

Key Actions:

• Read epic issue in GitHub Projects
• Analyze scope, value, and success criteria
• Identify user types and journeys covered

Step 2: Identify User Journeys

Key Actions:

• Map out user flows within the epic
• Apply task analysis, scenario mapping, and user type breakdown

Techniques:

• Task Analysis: Identify tasks users complete and their sequence
• Scenario Mapping: Document scenarios and paths users might take
• User Type Breakdown: Determine if different users need different stories

Step 3: Draft Initial Stories

Key Actions:

• Create draft stories covering the epic
• Start with happy paths, then add edge cases

Start with happy paths:

• Cover core functionality for primary scenarios
• Address most common user needs
• Include essential capabilities

Then add edge cases and variations:

• Add error handling stories
• Cover alternative flows
• Include advanced features

Verify coverage:

• Confirm all epic scope is covered
• Check for gaps in user journeys
• Ensure all success criteria are addressable

Step 4: Apply INVEST Criteria

Key Actions:

• Review each story against INVEST criteria
• Split or revise stories that fail criteria

Validation checklist:

• Independence: Verify story can be completed without others
• Value: Confirm it delivers something users care about
• Size: Check it's 1-5 days of work; split if larger
• Testability: Define acceptance criteria

Step 5: Add Acceptance Criteria

Key Actions:

• Define clear acceptance criteria for each story
• Use Given-When-Then format or simple checklist

Given-When-Then Format:

Given [context],
When [action],
Then [expected outcome].

Or simple checklist:

• Criterion 1
• Criterion 2
• Criterion 3

Example:

Story: "User can filter campaigns by date range"

Acceptance Criteria:

• Date picker UI for start date and end date
• Only campaigns with activity in date range are shown
• Selecting invalid range (end before start) shows error message
• Clearing filters shows all campaigns again

Step 6: Prioritize Stories

Key Actions:

• Determine sequence and priority for stories
• Apply MoSCoW framework for prioritization

Guidelines:

• Sequencing: Identify which stories must come first (dependencies)
• Prioritization: Rank by value using MoSCoW framework

Step 7: Create Story Issues in GitHub Projects

Key Actions:

• Create a GitHub issue for each story
• Set custom fields, labels, and parent link

Issue Configuration:

• Title: "[Story summary in user voice]"
• Description: Full story with acceptance criteria using template from references/story-template.md

Custom Fields:

• Type: Story
• Priority: [Must Have / Should Have / Could Have]
• Status: Not Started

Labels:

• type:story
• priority:[moscow-level]

Parent: Link to Epic issue as parent

Story Splitting

Split stories that are too large (more than 1 week of work) using these techniques:

For detailed guidance and examples for each technique, see references/splitting-techniques.md.

Best Practices

Write from User Perspective

Frame stories around what users see and experience:

• ❌ "Implement database indexes for performance"
• ✅ "Campaign list loads in under 2 seconds"

Keep Stories Testable

Include acceptance criteria for every story:

• Add 3-5 acceptance criteria per story
• Define specific, observable outcomes
• Ensure testability without looking at code

Avoid Technical Tasks as Stories

Convert technical work into tasks within user-facing stories:

• ❌ Story: "Set up CI/CD pipeline"
• ✅ Story: "User can see deployment status" (tasks include CI/CD setup)

One Story, One Goal

Limit each story to a singular focus:

• ❌ "User can edit profile and change password and upload avatar"
• ✅ Split into three separate stories

Include Non-Functional Requirements

Address quality attributes in stories:

• Include performance requirements
• Specify security constraints
• Define accessibility standards
• Document usability expectations

Common Pitfalls to Avoid

Quick Reference: Story Creation Flow

1. Review Epic → Understand scope, value, success criteria
2. Identify Journeys → Map user flows and scenarios
3. Draft Stories → Cover happy paths, then edge cases
4. Apply INVEST → Check and refine against criteria
5. Add Acceptance Criteria → Define testability for each story
6. Prioritize → Sequence and rank by value
7. Create Issues → Add to GitHub Projects as children of epic
8. Proceed → Move to task breakdown for each story

Reference Files

Load references as needed:

Examples

Working examples that can be copied and adapted:

Related Skills

Load these skills when story work reveals needs beyond this skill's scope:

Converted and distributed by TomeVault — claim your Tome and manage your conversions.