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.
Instrucciones de origen · Vista previa de solo lectura
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"}}
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...)
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
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
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
