Story Refinement

Transform vague, incomplete, or ambiguous user stories into clear, sprint-ready stories with well-defined acceptance criteria, test scenarios, and technical guidance.

Purpose

Apply structured refinement techniques to improve story quality:

• Enhance user story narrative (As a... I want... So that...)
• Develop comprehensive acceptance criteria (5-8 specific, testable AC)
• Add technical guidance (tech stack, patterns, security, data models)
• Identify edge cases (boundary conditions, unusual input, concurrency)
• Create test scenarios (unit, integration, E2E)
• Ensure definition of ready compliance (INVEST criteria)

When to Use This Skill

This skill should be used when:

• Story has vague or unclear requirements
• Acceptance criteria are missing or incomplete
• Story is too large and needs decomposition
• Technical approach is unclear
• Before sprint commitment (definition of ready check)
• After stakeholder feedback requiring clarification

This skill should NOT be used when:

• Story already has comprehensive AC and technical notes
• Story is just being created (use breakdown-epic first)
• Story is in progress (use refine-task instead)

Prerequisites

• Story file must exist in .claude/stories/
• Basic user story narrative present (or at minimum a title)
• General understanding of feature context

Sequential Refinement Process

Execute steps in order - each builds on previous enhancements:

Step 0: Load Story and Assess Quality

Purpose: Evaluate current story quality against definition of ready.

Actions:

1. Read story file from .claude/stories/{story-id}.md

2. Parse story components:

   • Title
   • User story narrative (As a... I want... So that...)
   • Acceptance criteria
   • Technical notes
   • Edge cases
   • Test scenarios
   • Dependencies

3. Assess quality against definition of ready (INVEST):

   • Independent: Can be worked on without other stories
   • Negotiable: Flexible on implementation details
   • Valuable: Delivers clear value to user/business
   • Estimable: Team can estimate with confidence
   • Small: Fits in one sprint (typically ≤13 points)
   • Testable: Clear how to verify it works

4. Calculate quality score (0-4 scale):

   Copy

   Quality Score = Average of:
   - Title quality (1-4)
   - Narrative quality (1-4)
   - AC quality (1-4)
   - Technical notes quality (1-4)
   - Edge cases coverage (1-4)
   - Dependencies clarity (1-4)
   

5. Identify specific gaps and determine refinement strategy

Output: Story assessment with current quality score (0-4 scale), sprint readiness (yes/no), issues identified (list), estimated refinement time

See: references/templates.md#step-0-story-quality-assessment-output for complete format and scoring rubric

Reference: See story-quality-assessment.md for detailed assessment criteria.

Step 1: Enhance User Story Narrative

Purpose: Transform vague narrative into clear, valuable user story.

Standard Format:

As a [persona],
I want to [action],
So that [benefit/value].

Actions:

1. Identify Persona:

   • Who is the user? (end user, admin, system, developer)
   • Be specific: "registered user" not just "user"

2. Clarify Action:

   • What does user want to do?
   • Use specific, action-oriented verbs
   • Avoid technical jargon unless developer story

3. Articulate Value:

   • Why does user want this?
   • What problem does it solve?
   • What outcome does it enable?

Example: "Users should be able to login" → "As a registered user, I want to log in with my email and password so that I can access my personalized account and data securely" (added persona, specified mechanism, articulated value)

See: references/templates.md#step-1-user-story-narrative-refinement for more before/after examples and patterns

Step 2: Develop Comprehensive Acceptance Criteria

Purpose: Define specific, testable criteria for "done".

AC Best Practices:

• Specific: No ambiguity about what needs to be true
• Testable: Can verify with a test case
• Implementation-independent: What, not how
• User-focused: From user perspective when possible
• Numbered: For easy reference (AC-1, AC-2, etc.)

AC Categories to Cover:

1. Happy Path (2-3 AC): Core functionality working correctly
2. Validation (2-3 AC): Input validation and format checking
3. Error Handling (2-3 AC): Failure scenarios with clear error messages
4. Security (1-2 AC): Authentication, authorization, data protection
5. Performance (1 AC): Response time or throughput requirements

Example: 2 vague AC ("Login works", "Error handling") → 11 specific, testable AC organized by category (Happy Path: 3, Validation: 2, Error Handling: 2, Security: 3, Performance: 1)

See: references/templates.md#step-2-acceptance-criteria-development for complete before/after examples and AC development patterns

Reference: See refinement-techniques.md for AC development patterns.

Step 3: Identify and Document Edge Cases

Purpose: Anticipate boundary conditions, unusual inputs, and failure scenarios.

Edge Case Categories:

1. Boundary Conditions: Min/max lengths, exactly at limit values
2. Unusual Input: Special characters, unicode, whitespace
3. Timing & Concurrency: Simultaneous requests, race conditions
4. State Transitions: User already logged in, account changes mid-operation
5. External Dependencies: Database down, Redis unavailable, network failures
6. Security Scenarios: Brute force, injection attempts, XSS

Example: For login story, identify 7+ edge cases: boundary (min password length), unusual input (+symbol in email, whitespace), concurrency (simultaneous logins), state transitions (password change mid-login), external dependencies (DB down), security (brute force)

See: references/templates.md#step-3-edge-cases-identification for complete edge case examples and identification guide

Reference: See refinement-techniques.md for edge case identification guide.

Step 4: Add Technical Guidance

Purpose: Provide technical context for implementation.

Technical Notes Structure:

1. Technology Stack: Languages, frameworks, libraries to use
2. Architecture Patterns: Repository, service layer, middleware patterns
3. Security Considerations: Hashing algorithms, rate limiting, validation
4. Data Models: Database schemas, field types, relationships
5. API Contracts: Request/response formats, status codes
6. Performance Requirements: Response times, throughput, indexes

Example: For login story, add tech stack (Node/Express/PostgreSQL/Redis/bcrypt/JWT), implementation approach (3-layer architecture), security (password hashing, rate limiting, no enumeration), data models (users table with lockout fields), API contract (POST endpoint with request/response formats), performance targets (< 500ms p95)

See: references/templates.md#step-4-technical-guidance for complete technical notes templates and examples

Reference: See story-templates.md for technical notes templates.

Step 5: Create Test Scenarios

Purpose: Define how to verify story works correctly.

Test Types:

1. Unit Tests (Fast, Isolated): Test individual functions
2. Integration Tests (Medium, With Dependencies): Test multiple components
3. E2E Tests (Slow, Full System): Test complete workflows
4. Performance Tests (Optional): Test under load

Example: For login story, create unit tests (email validation, password hashing), integration tests (success, failure, lockout), E2E tests (complete signup → login → protected access flow)

See: references/templates.md#step-5-test-scenarios for complete test scenario templates and examples

Reference: See refinement-techniques.md for test scenario templates.

Step 6: Define Story Size and Splitting Criteria

Purpose: Ensure story fits in one sprint (≤13 points).

Size Categories:

• XS (1-2 points): < 4 hours, minimal complexity
• S (3-5 points): 4-8 hours, moderate complexity
• M (8 points): 1-2 days, higher complexity
• L (13 points): 2-3 days, very complex
• XL (21+ points): MUST SPLIT

Splitting Triggers:

• Estimated at > 13 points
• More than 10 acceptance criteria
• Involves 3+ distinct components
• Team has low confidence in estimate (<70%)

Splitting Strategies:

1. By workflow steps (signup → verify email → complete profile)
2. By CRUD operations (view → edit → delete)
3. By persona (standard user → admin)
4. By priority (MVP → nice-to-have → future)
5. By happy path vs edge cases

Reference: See refinement-techniques.md for detailed splitting strategies.

Step 7: Update Story File with Refinements

Purpose: Save all refinements to story file.

Updated Story Structure: Story file includes title, ID, priority, status, estimate, user story (As a/I want/So that), categorized AC, technical notes, edge cases, test scenarios, dependencies, definition of done checklist

See: references/templates.md#step-7-complete-story-file-structure for full template and complete login story example

Reference: See story-templates.md for complete story template.

Step 8: Generate Refinement Report

Purpose: Document changes made and quality improvement.

Report File: .claude/refinements/{story-id}-refinement-{date}.md

Report Contents: Summary (quality before/after, sprint readiness), key improvements (narrative, AC count, technical notes, edge cases, test scenarios), specific changes (before/after comparisons), definition of ready assessment table, quality score breakdown, next steps (estimate, add to sprint, assign)

See: references/templates.md#step-8-refinement-report-template for complete report format with all sections

Step 9: Present Refinement Summary to User

Purpose: Communicate improvements clearly.

Summary Format: Display completion status, story ID/title, quality improvement (before/after/change), key enhancements checklist, sprint readiness, files updated, next steps (estimate, add to sprint, implement)

See: references/templates.md#step-9-refinement-summary for complete summary format

Common Refinement Patterns

Login Story: "Users can log in" → add persona, mechanism (email+password), AC (validation/errors/security), tech notes (JWT/bcrypt/rate limiting) CRUD Story: "Manage profile" → split into View/Edit/Delete (3 stories) with specific AC, API contracts, validation Integration Story: "Integrate payment" → add value, AC (success/failures/refunds), tech notes (API keys/webhooks/PCI compliance)

See: references/integration-patterns.md and references/templates.md for more refinement patterns and examples

Integration with Other Skills

Before Refinement:

• breakdown-epic → Create initial stories from epic (stories start rough, need refinement)

After Refinement:

• estimate-stories → Estimate refined stories (refinement increases confidence)
• sprint-plan → Add to sprint plan
• implement-feature → Implement with clear guidance

Best Practices

Refine collaboratively (involve dev/QA/PO) | Keep stories independent (minimize dependencies) | Make AC testable (specific numbers, exact error messages) | Document assumptions (what exists, what we're NOT building) | Balance detail vs flexibility (enough to estimate/implement, not constraining)

See: references/integration-patterns.md for workflow integration details

References

Detailed documentation in references/:

• templates.md: All output formats, before/after examples, complete story templates, refinement reports, test scenarios, technical notes templates, splitting strategies, AC development patterns
• story-quality-assessment.md: Quality matrix, definition of ready, assessment criteria, INVEST evaluation
• refinement-techniques.md: AC development patterns, edge case identification, test scenario creation, story splitting strategies
• story-templates.md: Before/after story examples, story file structures, technical notes templates
• integration-patterns.md: Common refinement patterns, workflow integration with other skills, best practices