name	user-story-generator
type	orchestrator
description	Create user stories from feature descriptions with interactive Q&A and automated validation
version	1.0.0
allowed_tools	Read, Write, Edit, Bash, Grep, Glob, Task

User Story Generator Skill

You are the main user story creation workflow. You guide users through feature extraction, decompose features into user stories, and coordinate validation and annotation.

Purpose

Transform feature descriptions into well-crafted, validated user stories with:

Interactive feature extraction
Intelligent story decomposition (2-8 stories)
Automated INVEST validation
Technical annotation
YAML and Markdown file creation
Optional GitHub integration

Activation

This skill is activated when users want to create new user stories from feature descriptions. Typical invocations:

"Create user stories for [feature description]"
"Break down this feature into stories: [description]"
"Generate stories for [feature]"

Workflow

Phase 1: Feature Extraction (Interactive)

Goal: Extract complete feature details through structured Q&A.

Receive Initial Description: User provides feature description (free-form)

Ask Clarifying Questions:

I'll help you create user stories for this feature. Let me gather some details:

1. **Primary User/Persona**: Who will use this feature?
   Options: CEO, Business Owner, General Manager, CFO, Sales Manager, New Owner, End User, Other

2. **Business Value**: What is the main benefit or objective?
   (e.g., "Increase decision-making speed", "Reduce operational costs")

3. **Key Requirements**: What are the must-have capabilities?
   (List 2-5 core requirements)

4. **Priority**: How urgent is this feature?
   Options: low, medium, high, critical

5. **Constraints**: Any technical, performance, or compliance requirements?
   (Optional)

6. **Dependencies**: Does this depend on other features or systems?
   (Optional)

Build Feature JSON:

{
  "title": "Dashboard Analytics for CEO",
  "description": "Provide CEO with real-time business metrics dashboard",
  "persona": "ceo",
  "business_value": "Enable data-driven decision making with real-time insights",
  "requirements": [
    "Real-time data updates",
    "Multiple chart types (line, bar, pie)",
    "Export to PDF",
    "Mobile responsive design"
  ],
  "priority": "high",
  "constraints": [
    "Must support 50+ concurrent users",
    "Page load time < 2 seconds"
  ],
  "dependencies": [
    "User authentication system",
    "Data warehouse integration"
  ]
}

Confirm with User:

📋 Feature Summary

**Title**: Dashboard Analytics for CEO
**Persona**: CEO
**Value**: Enable data-driven decision making with real-time insights
**Priority**: High

**Requirements**:
- Real-time data updates
- Multiple chart types (line, bar, pie)
- Export to PDF
- Mobile responsive design

**Constraints**:
- Must support 50+ concurrent users
- Page load time < 2 seconds

**Dependencies**:
- User authentication system
- Data warehouse integration

Does this look correct? Reply with:
- "yes" to proceed
- "modify [field]: [new value]" to make changes
- "no" to start over

Iterate if Needed: Allow modifications until user confirms.

Phase 2: Story Decomposition

Goal: Break feature into 2-8 INVEST-compliant user stories.

Analyze Scope: Determine appropriate number of stories based on:
- Feature complexity
- Number of requirements
- Natural workflow boundaries
- Technical layers
- Priority/MVP considerations

Generate Story IDs: Get next available IDs:

# Read counter from .story_counter file
# Generate: US-0001, US-0002, US-0003, etc.

Decompose Feature: Create story templates with:
- Unique ID: US-XXXX
- Title: Clear, action-oriented (verb + noun)
- User Story: "As a [persona], I want [goal], So that [benefit]"
- Acceptance Criteria: 2-5 Given/When/Then scenarios
- Story Points: Initial estimate (1, 2, 3, 5, 8)
- Priority: Inherited from feature or adjusted
- Dependencies: Links to blocking/blocked stories
- Tags: Relevant categories (UI, API, data, etc.)

Example Decomposition:

Feature: "Dashboard Analytics for CEO"

Story 1 (US-0001): "Display key business metrics"

id: US-0001
title: Display key business metrics on dashboard
story:
  as_a: CEO
  i_want: to see revenue, profit, and customer growth metrics on my dashboard
  so_that: I can quickly assess overall business performance at a glance

acceptance_criteria:
  - given: I am logged in as CEO
    when: I navigate to the dashboard
    then: I see revenue, profit, and growth metrics displayed

  - given: The metrics are displayed
    when: I hover over a metric
    then: I see the exact value and percentage change

  - given: Data is available
    when: The dashboard loads
    then: All metrics display within 2 seconds

metadata:
  story_points: 5
  priority: high
  status: backlog
  tags: [ui, api, dashboard]

dependencies:
  blocks: [US-0002, US-0003]

Story 2 (US-0002): "Filter metrics by date range"

id: US-0002
title: Filter dashboard metrics by custom date range
story:
  as_a: CEO
  i_want: to filter metrics by custom date ranges
  so_that: I can analyze trends over specific time periods

acceptance_criteria:
  - given: I am on the dashboard
    when: I select a date range filter
    then: All metrics update to show data for that period

  - given: I have selected a custom date range
    when: I apply the filter
    then: The dashboard updates within 1 second

metadata:
  story_points: 3
  priority: medium
  status: backlog
  tags: [ui, filter, dashboard]

dependencies:
  blocked_by: [US-0001]
  blocks: []

Story 3 (US-0003): "Export dashboard to PDF" Story 4 (US-0004): "Mobile-responsive dashboard layout"

Story Quality Checklist:
- Each story delivers value independently
- Stories can be developed in parallel (except dependencies)
- Total story points reasonable (2-50 range typical)
- Acceptance criteria are specific and testable
- No circular dependencies
- All stories link back to feature

Phase 3: Automated Validation

Goal: Validate all stories against INVEST criteria silently.

Create YAML Files First:

# Write stories to stories/yaml-source/US-XXXX.yaml
# One file per story

Run Validation Script for each story:

python3 .claude/skills/story-validator/scripts/validate_story_invest.py --story-id US-0001 --save --output json
python3 .claude/skills/story-validator/scripts/validate_story_invest.py --story-id US-0002 --save --output json
# ... for all stories

Process Validation Results:
- Parse JSON output
- Check invest_score field (0-100)
- Check passed field (boolean)
- Collect issues array
Auto-Fix Issues (if possible):
- Missing "so that": Generate from business_value
- No story points: Estimate based on complexity
- Insufficient acceptance criteria: Add standard scenarios
- Vague benefits: Make more specific

Report Validation Summary:

🔍 Story Validation Results

✅ US-0001: Display key business metrics (Score: 85/100)
✅ US-0002: Filter metrics by date range (Score: 90/100)
⚠️  US-0003: Export dashboard to PDF (Score: 75/100)
   Issue: Consider adding more acceptance criteria for error cases
✅ US-0004: Mobile-responsive layout (Score: 88/100)

Overall: 4/4 stories passed validation
Average score: 85/100

Phase 4: Technical Annotation

Goal: Add technical context using technical-annotator-agent.

Invoke Agent for each story:
```
Technical annotation for US-0001...
```
The technical-annotator-agent will:
- Analyze requirements
- Identify tech stack
- Suggest implementation approach
- Estimate effort
- Identify risks
- Update YAML files

Verify Updates: Check that technical section added to YAML:

technical:
  tech_stack:
    frontend: [React, TypeScript, Recharts]
    backend: [FastAPI, Python]
    database: [PostgreSQL]

  implementation_hints:
    - Use React Query for data fetching
    - Implement caching for metrics
    - Use WebSocket for real-time updates

  affected_components:
    - Dashboard component
    - Metrics API endpoints
    - Database views

  effort_estimate: "2-3 days"
  complexity: medium

  risks:
    - Performance with large datasets
    - Real-time update latency

Report Summary:

🛠️  Technical Annotations Added

US-0001: Display key business metrics
- Stack: React, TypeScript, FastAPI, PostgreSQL
- Effort: 2-3 days | Complexity: Medium
- Risk: Performance with large datasets

US-0002: Filter metrics by date range
- Stack: React Query, date-fns, FastAPI
- Effort: 1-2 days | Complexity: Low
- Risk: None identified

US-0003: Export dashboard to PDF
- Stack: react-to-pdf, jsPDF
- Effort: 1 day | Complexity: Low
- Risk: Layout consistency across browsers

US-0004: Mobile-responsive layout
- Stack: Tailwind CSS, React responsive hooks
- Effort: 2 days | Complexity: Medium
- Risk: Touch interaction edge cases

Phase 5: Generate Documentation

Goal: Create Markdown documentation for all stories.

Run Generation Script:

python3 .claude/skills/user-story-generator/scripts/generate_story_from_yaml.py --story-id US-0001
python3 .claude/skills/user-story-generator/scripts/generate_story_from_yaml.py --story-id US-0002
python3 .claude/skills/user-story-generator/scripts/generate_story_from_yaml.py --story-id US-0003
python3 .claude/skills/user-story-generator/scripts/generate_story_from_yaml.py --story-id US-0004

Verify Files Created:

✅ Generated documentation:
- stories/generated-docs/US-0001.md
- stories/generated-docs/US-0002.md
- stories/generated-docs/US-0003.md
- stories/generated-docs/US-0004.md

Phase 6: GitHub Integration (Optional)

Goal: Create GitHub issues if enabled in config.

Check Configuration:

# Read config/automation-config.yaml
# Check: github.enabled and github.auto_sync

Create Issues (if enabled):

python3 .claude/skills/user-story-generator/scripts/github_sync.py bulk create US-0001 US-0002 US-0003 US-0004

Report Results:

🔗 GitHub Integration

✅ Created issues:
- US-0001: https://github.com/owner/repo/issues/42
- US-0002: https://github.com/owner/repo/issues/43
- US-0003: https://github.com/owner/repo/issues/44
- US-0004: https://github.com/owner/repo/issues/45

Labels applied: story-points-X, persona-ceo, priority-high

OR if disabled:

ℹ️  GitHub integration disabled in config
To enable: Set github.enabled: true in config/automation-config.yaml

Phase 7: Final Summary

Goal: Provide comprehensive summary and next steps.

Present complete summary:

✅ User Stories Created Successfully!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📊 Summary

Feature: Dashboard Analytics for CEO
Stories: 4 created
Total Points: 16 (US-0001: 5, US-0002: 3, US-0003: 3, US-0004: 5)
Validation: 4/4 passed (avg score: 85/100)
GitHub: ✅ Issues created (#42-45)

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📝 Stories Created

1. ✅ US-0001: Display key business metrics (5 pts)
   Tech: React, TypeScript, FastAPI, PostgreSQL
   Effort: 2-3 days | Complexity: Medium

2. ✅ US-0002: Filter metrics by date range (3 pts)
   Tech: React Query, date-fns, FastAPI
   Effort: 1-2 days | Complexity: Low
   Dependencies: Blocked by US-0001

3. ✅ US-0003: Export dashboard to PDF (3 pts)
   Tech: react-to-pdf, jsPDF
   Effort: 1 day | Complexity: Low
   Dependencies: Blocked by US-0001

4. ✅ US-0004: Mobile-responsive layout (5 pts)
   Tech: Tailwind CSS, React responsive hooks
   Effort: 2 days | Complexity: Medium
   Dependencies: Blocked by US-0001

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

📁 Files Created

YAML Source:
- stories/yaml-source/US-0001.yaml
- stories/yaml-source/US-0002.yaml
- stories/yaml-source/US-0003.yaml
- stories/yaml-source/US-0004.yaml

Documentation:
- stories/generated-docs/US-0001.md
- stories/generated-docs/US-0002.md
- stories/generated-docs/US-0003.md
- stories/generated-docs/US-0004.md

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🔗 GitHub Issues

- US-0001: #42 - https://github.com/owner/repo/issues/42
- US-0002: #43 - https://github.com/owner/repo/issues/43
- US-0003: #44 - https://github.com/owner/repo/issues/44
- US-0004: #45 - https://github.com/owner/repo/issues/45

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

🎯 Next Steps

1. Review stories: Open stories/generated-docs/US-*.md
2. Validate quality: Use story-validator skill if needed
3. Analyze dependencies: Run dependency-analyzer skill
4. Plan sprint: Use sprint-planner skill (e.g., capacity: 20 points)
5. Start development!

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

💡 Available Actions

- Refine a story: "Refine US-0001 to add more acceptance criteria"
- Add more stories: "Add a story for [new requirement]"
- Validate stories: "Validate all stories in backlog"
- Analyze dependencies: "Check dependencies for these stories"
- Plan sprint: "Plan sprint with 40 story points"

Integration with Scripts

This skill orchestrates multiple Python scripts:

Story Counter Management

# Read current counter
cat .story_counter  # Returns next ID number

# Increment counter (automatic on story creation)
echo $(($(cat .story_counter) + 1)) > .story_counter

Validation

python3 .claude/skills/story-validator/scripts/validate_story_invest.py --story-id US-0001 --save --output json

Markdown Generation

python3 .claude/skills/user-story-generator/scripts/generate_story_from_yaml.py --story-id US-0001

Batch Operations

python3 .claude/skills/user-story-generator/scripts/batch_story_generator.py --story-ids US-0001,US-0002,US-0003

GitHub Sync

python3 .claude/skills/user-story-generator/scripts/github_sync.py bulk create US-0001 US-0002 US-0003 US-0004

Integration with Agents

This skill coordinates sub-agents using the Task tool:

QA Validator Agent

# For validation of stories
Use qa-validator-agent to validate US-0001

Technical Annotator Agent

# For adding technical context
Use technical-annotator-agent to annotate US-0001

Error Handling

Validation Failures

If validation score < 50:

⚠️  Validation Issues Detected

US-0003 failed validation (Score: 45/100)

Issues found:
- Missing "so that" benefit statement
- No story points assigned
- Only 1 acceptance criterion (minimum 2 required)

🔧 Auto-fixing issues...

✅ Added benefit: "So that I can share insights in board meetings"
✅ Assigned story points: 3 (based on similar stories)
✅ Added acceptance criterion: Error handling scenario

Re-running validation...
✅ US-0003 now passes (Score: 75/100)

Script Failures

If Python script fails:

❌ Error: Validation script failed

Error: FileNotFoundError: Story file not found: US-0001.yaml

This usually means:
- Story YAML file wasn't created
- Wrong story ID
- File permissions issue

🔧 Recovery steps:
1. Verify story ID: US-0001
2. Check file exists: stories/yaml-source/US-0001.yaml
3. Check file permissions

Would you like me to:
- Recreate the story file
- Try a different story ID
- Check the directory structure

GitHub Sync Failures

If GitHub API fails:

⚠️  GitHub sync partially failed

✅ Created: US-0001 (#42), US-0002 (#43)
❌ Failed: US-0003, US-0004

Error: API rate limit exceeded

Stories are created locally and can be synced later:
python3 scripts/github_sync.py bulk create US-0003 US-0004

Configuration

Load settings from .claude/skills/user-story-generator/config/automation-config.yaml:

generation:
  min_stories_per_feature: 2
  max_stories_per_feature: 8
  default_story_points: 3

validation:
  invest:
    strict_mode: false  # If true, block creation on validation failure

github:
  enabled: true
  auto_sync: true

automation:
  auto_generate_markdown: true
  auto_validate_on_save: true

Best Practices

Story Decomposition

Start with core MVP functionality (Story 1)
Build foundation stories first, enhancements later
Keep stories focused on single capability
Ensure each story is independently valuable
Use dependencies sparingly

User Interaction

Ask targeted questions, not open-ended
Provide examples and options
Confirm understanding before proceeding
Show progress during long operations
Provide clear next steps

Quality Assurance

Validate before creating files
Use specific, testable acceptance criteria
Estimate story points realistically
Check dependencies are logical
Ensure technical context is accurate

Examples

Example 1: Simple Feature

Input:

Create stories for: User profile editing

Output:

I'll help create user stories for profile editing. Let me gather details:

1. Primary user? (Options: End User, Admin, etc.)
[User answers: End User]

2. What fields can be edited? (e.g., name, email, photo, bio)
[User answers: name, email, profile photo, bio]

3. Priority? (low/medium/high/critical)
[User answers: medium]

[Shows confirmation, user confirms]

✨ Generating stories...

Created 3 stories:
- US-0005: Edit basic profile information (3 pts)
- US-0006: Upload and crop profile photo (5 pts)
- US-0007: Preview profile changes before saving (2 pts)

[Full summary follows]

Example 2: Complex Feature with Dependencies