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.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
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
