refine-story

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:

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