> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blitzy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Generate User Stories

> Transform objectives into comprehensive user epics with testable acceptance criteria

Translating a product objective into a well-structured backlog of stories is time-consuming work that often bottlenecks on a single PM or tech lead. Blitzy accelerates this: give it a high-level objective and it produces a full epic/feature/story hierarchy with BDD acceptance criteria, organized as markdown files in your `tickets/` directory and ready for sprint planning.

<Card title="Ready to generate user stories?" icon="rocket" href="/templates/feature-product-development/user-story-generation">
  Use the **User Story Generation Template** to get started with a structured prompt
</Card>

<Note>
  **Jump to:** [Workflow](#workflow) | [When to Use](#when-to-use-this-approach) | [Prompt Structure](#prompt-structure) | [Key Considerations](#key-considerations) | [Common Patterns](#common-patterns) | [Troubleshooting](#troubleshooting) | [Validation Checklist](#validation-checklist)
</Note>

## Workflow

This workflow generates structured ticket files that serve as automated development references:

<Steps>
  <Step title="Write Prompt">
    Leverage the User Story Generation Template, provide clear objective statement, and define scope and boundaries.
  </Step>

  <Step title="Optional: Refine Prompt with LLMs">
    Use Claude or other LLMs to refine objective clarity, ensure business value is well-articulated, and validate scope definitions.
  </Step>

  <Step title="Review and Iterate on AAP">
    Carefully review the generated Agent Action Plan, verify epic/feature/story breakdown matches requirements, and iterate on AAP if needed before triggering generation.
  </Step>

  <Step title="Review Output">
    Examine generated epics, features, and stories. Validate story quality and check acceptance criteria completeness.
  </Step>

  <Step title="Optional: Refine Stories">
    Request modifications to specific stories if needed, adjust acceptance criteria or edge cases, and maintain focus on original objective scope.
  </Step>

  <Step title="Merge to Codebase">
    Merge approved ticket files into your codebase repository. These files serve as references for subsequent Blitzy development runs, enabling you to reference features and their stories in your prompts (e.g., "Implement FEATURE-001-01 including all child stories per the acceptance criteria defined in tickets/EPIC-001/FEATURE-001-01/...") while maintaining tight correlation between tickets and implementation.
  </Step>
</Steps>

## When to Use This Approach

<Tabs>
  <Tab title="Backlog Kickstart">
    Turn a high-level objective into a sprint-ready backlog of stories with estimation guidance and definition of done.
  </Tab>

  <Tab title="Feature Breakdown">
    Decompose complex features into implementable increments organized as epics, features, and stories.
  </Tab>

  <Tab title="Acceptance Criteria">
    Generate testable Given/When/Then BDD criteria that cover happy paths, edge cases, and error scenarios.
  </Tab>

  <Tab title="Dependency Mapping">
    Surface dependencies, ordering constraints, and edge cases systematically across every story.
  </Tab>
</Tabs>

## Prompt Structure

Follow the [Golden Rules](/prompt-engineering/golden-rules) when writing your user story generation prompt. Focus especially on:

* **Objective Clarity** - State business goal, target users, and expected outcomes explicitly
* **Scope Boundaries** - Define what's included and excluded from the epic/features
* **Story Structure** - Specify epic numbering, sprint duration, and story point limits
* **Acceptance Criteria** - Require BDD format (Given/When/Then) and coverage categories

## Key Considerations

<CardGroup cols={2}>
  <Card title="Objective Clarity Drives Quality" icon="bullseye">
    State the business objective, target users, expected value, and scope boundaries explicitly. Vague objectives produce generic stories without actionable acceptance criteria.
  </Card>

  <Card title="Story Size Constraints Prevent Bloat" icon="ruler">
    Specify sprint duration and story point limits (typically 2-5 days per story, max 8 points). Without size guidance, generated stories may be too large for single sprint completion.
  </Card>

  <Card title="Epic/Feature Structure Needs Definition" icon="sitemap">
    For large objectives, specify how many features per epic (2-4 recommended) and stories per feature (3-8 recommended). Otherwise breakdown may not align with your team's workflow.
  </Card>

  <Card title="Story Quality Principles Matter" icon="clipboard-check">
    Every story must be Independent, Negotiable, Valuable, Estimable, Sized appropriately, and Testable (INVEST). Reference these principles explicitly in your prompt.
  </Card>
</CardGroup>

## Common Patterns

**Feature with frontend and backend** - Objective: "Add user authentication with OAuth2 providers" breaks into OAuth Integration (backend), Login UI (frontend), and Account Management (profile/sessions).

**Incremental capability rollout** - Objective: "Enable multi-language support" breaks into Core i18n Infrastructure (detection, externalization), Initial Language Support (2-3 languages), and Language Management (user selection, admin tools).

**Multi-actor workflow** - Objective: "Implement approval workflow for expense reports" breaks into Expense Submission (employee), Manager Review (approve/reject), and Finance Processing (final approval, payment tracking).

## Troubleshooting

<AccordionGroup>
  <Accordion title="Stories are too large">
    Add size constraints to prompt: "Break down into stories completable in 2-3 days" or "Each story should be 3 story points or less". Review epic/feature breakdown and split large features.
  </Accordion>

  <Accordion title="Acceptance criteria lack specificity">
    Add to prompt: "Include specific values, thresholds, and measurable outcomes in acceptance criteria. Avoid vague terms like approximately, various, properly, or efficiently."
  </Accordion>

  <Accordion title="Epic breakdown doesn't match architecture">
    Provide architecture context in prompt: "Feature boundaries should align with microservices: auth-service, user-service, notification-service" or "Group stories by backend vs. frontend work".
  </Accordion>

  <Accordion title="Missing edge cases">
    Specify domain scenarios in prompt: "Include edge cases for concurrent user sessions, network timeouts, and data race conditions" and reference system constraints like database limits or API rate limiting.
  </Accordion>

  <Accordion title="Stories lack quality structure">
    Add explicit validation instruction: "Ensure each story is Independent, Negotiable, Valuable, Estimable, Sized appropriately, and Testable" and review generated stories against checklist.
  </Accordion>
</AccordionGroup>

## Validation Checklist

After generation, verify story quality, acceptance criteria, and file structure:

* [ ] Each story is independent and can be implemented standalone
* [ ] Stories are negotiable and can be adjusted before commitment
* [ ] Stories deliver clear value to users with measurable outcomes
* [ ] Stories are properly sized (completable in one sprint, typically 2-5 days)
* [ ] All acceptance criteria use Given/When/Then BDD format
* [ ] Coverage includes input validation, expected output, error handling, edge cases
* [ ] No forbidden vague terms (approximately, various, properly, efficiently)
* [ ] WHO/WHAT/WHY format followed for all user stories
* [ ] Sub-tasks defined with action verbs and assignee placeholders
* [ ] All files in `tickets/` directory with correct naming convention