name: refine-story description: Transform vague or incomplete user stories into sprint-ready stories with clear acceptance criteria, test scenarios, and technical guidance. This skill should be used before sprint commitment for definition of ready check. acceptance:

story_quality_improved: "Story quality score increased by at least 1 point on 4-point scale"
acceptance_criteria_complete: "At least 5 specific, testable acceptance criteria defined"
technical_guidance_provided: "Technical notes added with tech stack, patterns, security, and data models"
definition_of_ready_met: "Story meets all 6 INVEST criteria (Independent, Negotiable, Valuable, Estimable, Small, Testable)" inputs: story_id: type: string required: true description: "ID of story file in .claude/stories/" focus: type: enum values: ["all", "acceptance-criteria", "technical-notes", "edge-cases", "test-scenarios"] default: "all" description: "Specific aspect to focus refinement on" interactive: type: boolean default: false description: "Ask user questions during refinement for clarification" outputs: refined_story: type: object description: "Updated story with enhanced narrative, AC, technical notes, edge cases, test scenarios" quality_score_before: type: number description: "Quality score before refinement (0-4 scale)" quality_score_after: type: number description: "Quality score after refinement (0-4 scale)" ready_for_sprint: type: boolean description: "Whether story meets definition of ready" refinement_report: type: string description: "Path to detailed refinement report file" telemetry: emit: "skill.refine-story.completed" track:
- story_id
- duration_ms
- quality_score_before
- quality_score_after
- quality_improvement
- ac_count_before
- ac_count_after
- ready_for_sprint

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:

Read story file from .claude/stories/{story-id}.md
Parse story components:
- Title
- User story narrative (As a... I want... So that...)
- Acceptance criteria
- Technical notes
- Edge cases
- Test scenarios
- Dependencies
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

Calculate quality score (0-4 scale):

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)

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:

Identify Persona:
- Who is the user? (end user, admin, system, developer)
- Be specific: "registered user" not just "user"
Clarify Action:
- What does user want to do?
- Use specific, action-oriented verbs
- Avoid technical jargon unless developer story
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:

Happy Path (2-3 AC): Core functionality working correctly
Validation (2-3 AC): Input validation and format checking
Error Handling (2-3 AC): Failure scenarios with clear error messages
Security (1-2 AC): Authentication, authorization, data protection
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:

Boundary Conditions: Min/max lengths, exactly at limit values
Unusual Input: Special characters, unicode, whitespace
Timing & Concurrency: Simultaneous requests, race conditions
State Transitions: User already logged in, account changes mid-operation
External Dependencies: Database down, Redis unavailable, network failures
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:

Technology Stack: Languages, frameworks, libraries to use
Architecture Patterns: Repository, service layer, middleware patterns
Security Considerations: Hashing algorithms, rate limiting, validation
Data Models: Database schemas, field types, relationships
API Contracts: Request/response formats, status codes
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:

Unit Tests (Fast, Isolated): Test individual functions
Integration Tests (Medium, With Dependencies): Test multiple components
E2E Tests (Slow, Full System): Test complete workflows
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:

By workflow steps (signup → verify email → complete profile)
By CRUD operations (view → edit → delete)
By persona (standard user → admin)
By priority (MVP → nice-to-have → future)
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

refine-story

$ 설치