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:

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:

## 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

## 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

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

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

gh project list --owner <owner> 2>&1

Create a project if needed

gh project create --owner <owner> --title "<Repo Name>" --format json 2>&1

Link project to repo

gh project link <project-number> --owner <owner> --repo <owner>/<repo> 2>&1

Add issues to the project

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:

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