user-story-writing

Imported from aws-solutions/konductor (skills/user-story-writing/SKILL.md). Install upstream with npx skills add aws-solutions/konductor --skill user-story-writing. Copyright stays with the author.

User Story Writing

Overview

Transforms business requirements (BRD, feature descriptions, requirements docs) into Epics and User Stories following INVEST principles with testable acceptance criteria.

Usage

Use this skill when:

• Converting a validated requirements document into development-ready stories
• Breaking down a feature into sprint-ready stories
• Creating acceptance criteria for existing stories

Core Concepts

INVEST Principles

Every user story must be Independent (no blocking dependencies), Negotiable (captures essence without over-specifying), Valuable (clear value to a specific user), Estimable (enough detail to estimate effort), Small (completable in one sprint, 1-5 days), and Testable (clear, verifiable acceptance criteria).

Artifact Structure

Epics contain a title (5-10 words), description (2-4 sentences of business objective), and 3-5 key objectives. User stories follow "As a [persona], I want [action] so that [benefit]" with 3-8 testable acceptance criteria per story.

Scope Options

MVP produces 10-15 stories for fastest path to value. Production produces 20-30 stories for full feature set. Full scope produces 30-40 stories including edge cases.

Execution

When this skill is activated, use the following as your full instruction set for generating user stories. Apply the Quality Gate at the end before presenting output to the user.

<user_story_structure>

• Title: Clear, concise description (3-8 words)
• Description: "As a type of user, I want goal so that benefit"
• Acceptance Criteria: 3-8 testable conditions in bulleted list format </user_story_structure> </artifact_structures>

When analyzing requirements from any input source, I will follow this systematic approach:

1. First, identify the input type and format:

• Uploaded document (Word, PDF, Excel, etc.)
• Free text requirements
• Partially structured content

2. For document-based inputs:

• Acknowledge the document type and size
• Extract key sections relevant to requirements
• Organize content into potential epics and stories
• Preserve traceability to original sections

3. For all extracted requirements, determine appropriate scope:

• Epic: Large feature requiring multiple sprints or teams
• User Story: Deliverable value within a single sprint

4. For Epic-level requirements:

• Create an Epic with title and description
• Identify 3-5 key business objectives
• Break down into 3-8 constituent User Stories
• Ensure stories are cohesive and collectively fulfill the Epic

5. For User Story-level requirements:

• Apply INVEST criteria for validation:

• Independent: Can be developed without dependencies on other stories

• Negotiable: Captures the essence without over-specifying implementation

• Valuable: Delivers clear value to stakeholders

• Estimable: Contains sufficient detail to be estimated

• Small: Can be completed within a single iteration

• Testable: Has clear acceptance criteria

• Create specific, testable acceptance criteria (3-8 items)

• Suggest Epic grouping if related to larger feature

• Ensure proper format with title, description, and acceptance criteria

6. For all requirements, I will:

• Keep stories small and focused (one capability per story)
• Separate different filtering, sorting, and display criteria into distinct stories
• Avoid technical implementation details in acceptance criteria
• Focus on observable behaviors and outcomes
• Ensure traceability to business objectives
• Highlight any assumptions or dependencies

7. When requirements are ambiguous or incomplete:

• Identify specific information gaps
• Suggest reasonable assumptions
• Provide options for the user to consider
• Ask targeted questions to gather necessary details

8. For large volumes of extracted requirements:

• Organize into logical groupings
• Present a summary view with option to expand details
• Identify highest-priority elements based on business value
• Suggest a phased approach if appropriate

<user_context> This section will contain the user's uploaded documents, pasted text, or written requirements that need to be transformed into structured agile artifacts. The content here will be processed according to the file_processing and instructions sections. Content may include:

1. Free-text business requirements
2. Uploaded product requirement documents
3. Feature descriptions
4. Technical specifications
5. Legacy documentation
6. Partial user stories
7. Business problem statements The system will parse this content and process it according to the defined methodology, referring back to specific elements when providing recommendations and structured outputs. </user_context>

Quality Gate

CRITICAL (must fix):

• Stories are not independent (circular dependencies between stories)
• Acceptance criteria describe implementation details instead of observable behavior
• Stories are too large to complete in one sprint (1-5 days)
• Missing error conditions and edge cases in acceptance criteria

IMPORTANT (should fix):

• Personas are generic ("user", "admin") instead of specific ("enterprise DevOps engineer")
• Acceptance criteria use vague terms ("fast", "easy") instead of measurable outcomes
• Stories missing performance or scale requirements where applicable

SUGGESTION:

• Could decompose XL stories further
• Could add non-functional requirements as explicit stories

Present findings as: CRITICAL → IMPORTANT → SUGGESTION. Ask: "Fix these issues? [y/n]" — unless scope_confirmed is true, in which case report all the findings and leave fixing to the caller, without asking.