# Creating User Stories

> Creates development plans with user stories and GitHub issues. Use when asked to plan features, create stories, write issues, build a backlog, or create a development roadmap.

- Skill: `andysolomon/creating-user-stories` (Agent Skill)
- Install (CLI): `npx skillmds@latest add andysolomon/creating-user-stories`
- Raw SKILL.md: https://api.skillmd.com/api/skills/andysolomon/creating-user-stories/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Product & Planning
- Author: andysolomon (https://skillmd.com/u/andysolomon)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/andysolomon/creating-user-stories

---


# Creating User Stories

Generates structured development plans with user stories in Gherkin syntax grouped into epics, creates GitHub issues with labels, and adds them to a GitHub Project for kanban workflow.

## Workflow

1. **Analyze the codebase** using the oracle tool to understand architecture, identify gaps, and recommend improvements
2. **Present the plan** to the user organized by epics/themes before creating issues
3. **Create GitHub labels** for epics, priorities, and sizes
4. **Create GitHub issues** using the `gh` CLI with Gherkin acceptance criteria
5. **Create or find a GitHub Project** for the repo and add all issues to it
6. **Link the project** to the repo so it appears in the repo's Projects tab

## Story Numbering

Every story must have a sequential ID prefixed with `W-` and zero-padded to 6 digits:

- `W-000001`, `W-000002`, ... `W-000024`

The ID is prepended to the issue title in brackets: `[W-000001] Replace placeholder weather values`

Before creating issues, check the highest existing story number:
```bash
gh issue list --limit 100 --state all --json title --jq '.[].title' | grep -oP 'W-\d+' | sort -r | head -1
```
If no stories exist, start at `W-000001`. Otherwise increment from the highest.

## Story Format (Gherkin Syntax)

Every story must use Gherkin syntax for acceptance criteria:

```markdown
## User Story
**ID:** W-000001

As a [user/developer/maintainer], I want [goal] so that [benefit].

## Acceptance Criteria

### Scenario: [Descriptive scenario name]
**Given** [precondition]
**When** [action]
**Then** [expected outcome]
**And** [additional outcome]

### Scenario: [Another scenario]
**Given** [precondition]
**When** [action]
**Then** [expected outcome]
**But** [negative assertion]

## Context
Brief technical context referencing specific files or patterns.
```

### Gherkin Guidelines

- Each acceptance criterion is a **Scenario** with Given/When/Then steps
- Use **And** for additional steps within Given/When/Then
- Use **But** for negative assertions within Then
- Scenario names should be descriptive and testable
- Keep steps atomic — one action or assertion per line
- Use concrete values over vague descriptions

### Example Issue Body

```markdown
## User Story
**ID:** W-000015

As a mobile user, I want the weather panel to fit naturally on small screens so that I can browse comfortably.

## Acceptance Criteria

### Scenario: Panel renders as full-height sheet on mobile
**Given** the viewport width is 375px or less
**When** I open a city's weather panel
**Then** the panel spans the full viewport height
**And** the close button is within thumb reach

### Scenario: Charts stack vertically without horizontal scroll
**Given** I am viewing the dashboard on a mobile device
**When** the charts section renders
**Then** all charts stack in a single column
**And** no horizontal scrollbar appears

## Context
Panel component: `src/components/WeatherPanel.tsx`
```

## Labels

Create and apply these label categories:

### Epic labels (use distinct colors)
- `epic: <name>` — Group related stories (e.g., `epic: performance`, `epic: accessibility`)

### Priority labels
- `priority: P0` (color: `b60205`) — Must do, blocking or critical
- `priority: P1` (color: `d93f0b`) — Should do, important for quality
- `priority: P2` (color: `fbca04`) — Nice to have, polish

### Size labels
- `size: S` (color: `c5def5`) — Small, < 1 day
- `size: M` (color: `bfd4f2`) — Medium, 1-3 days
- `size: L` (color: `85bbf0`) — Large, 3-5 days
- `size: XL` (color: `6fa8dc`) — Extra large, 5+ days or needs decomposition

## Creating Labels

```bash
gh label create "epic: <name>" --color "<hex>" --description "<description>" 2>&1 || true
gh label create "priority: P0" --color "b60205" --description "Must do" 2>&1 || true
```

## Creating Issues

```bash
gh issue create \
  --title "[W-000001] Short descriptive title" \
  --label "epic: <name>,priority: P1,size: M" \
  --body "## User Story
**ID:** W-000001

As a user, I want ...

## Acceptance Criteria

### Scenario: ...
**Given** ...
**When** ...
**Then** ...

## Context
..."
```

## GitHub Projects Integration

Every repo should have a GitHub Project for kanban-style story management. After creating issues, always add them to the project and link the project to the repo.

### Check for existing projects
```bash
gh project list --owner <owner> 2>&1
```

### Create a project if needed
```bash
gh project create --owner <owner> --title "<Repo Name>" --format json 2>&1
```

### Link project to repo
```bash
gh project link <project-number> --owner <owner> --repo <owner>/<repo> 2>&1
```

### Add issues to the project
```bash
for i in $(seq <start> <end>); do
  gh project item-add <project-number> --owner <owner> \
    --url "https://github.com/<owner>/<repo>/issues/$i" 2>&1
done
```

### Auth scopes
If `gh project` commands fail with a scopes error, refresh auth:
```bash
gh auth refresh -s read:project,project --hostname github.com
```

## Oracle Prompt Template

When consulting the oracle for story generation, use this structure:

```
Analyze this [app type] and create a comprehensive development plan with user stories
for the next phase. The app uses [tech stack summary].

Create well-structured stories grouped into epics/themes. Each story should have:
- A clear title
- User story format (As a user, I want... so that...)
- Acceptance criteria as Gherkin scenarios (Given/When/Then)
- Priority (P0-P3)
- Estimated complexity (S/M/L/XL)

Focus on realistic improvements: performance, UX polish, accessibility, testing,
mobile experience, and new features. Consider what's missing or could be better.
```

Pass key source files to the oracle for context.

## Guidelines

- **Gherkin always**: All acceptance criteria must use Given/When/Then scenarios
- **P0 stories first**: Always recommend starting with foundation/trust issues before features
- **Realistic scope**: Each story should be independently deliverable
- **Testable scenarios**: Every scenario should map to a verifiable test case
- **No duplicates**: Check existing issues with `gh issue list` before creating
- **Parallel creation**: Batch issue creation into parallel Task calls for speed
- **Always add to project**: Every issue must be added to the repo's GitHub Project
- **Always link project**: Project must be linked to the repo with `gh project link`
- **Escape special chars**: Use `\` for backticks and special markdown in `--body` args
- **Verify after**: Run `gh issue list --limit 50 --state open` to confirm all issues created