メニュー
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.
デフォルトでは、最初にソースを確認する Prompt が選択されています。直接コマンドに切り替えるか、ローカルコピーをダウンロードすることもできます。
インストールを決める前に、SKILL.md と SkillsMP に表示されている付属ファイルをお読みください。
Codex または Claude でインストール この Prompt をコピーして Codex、Claude、または他のアシスタントに貼り付けると、Skill ページを確認してインストールできます。
直接コマンドでは確認用 Prompt が省略されます。実行前にソースを確認してください。
npx skills add https://github.com/adolfoaranaes12/BMAD-ENHANCED --skill refine-storyコマンドは1行のまま表示されます。コピー前に横へスクロールして全体を確認してください。
ローカルで確認しますか？SkillsMP が現在取得できるファイルをダウンロードできます。
Comprehensive brownfield architecture analysis for existing codebases. Discovers structure, identifies patterns, assesses quality, calculates production readiness, and provides actionable recommendations. Use when analyzing existing codebases to understand architecture, assess quality, or prepare for modernization.
Systematically consume QA quality gate outputs and apply prioritized fixes for high-severity issues, NFR failures, and test coverage gaps. Use when quality review identifies issues requiring remediation.
Peer review architecture for quality, risks, and optimization opportunities. Analyzes scalability bottlenecks, security vulnerabilities, performance optimization, technology fit, and provides prioritized recommendations. Use when reviewing proposed architecture documents for quality assurance, risk identification, or architectural decision validation.
SOC 職業分類に基づく
SKILL.md を表示中
| 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"]} |
Transform vague, incomplete, or ambiguous user stories into clear, sprint-ready stories with well-defined acceptance criteria, test scenarios, and technical guidance.
Apply structured refinement techniques to improve story quality:
This skill should be used when:
This skill should NOT be used when:
.claude/stories/Execute steps in order - each builds on previous enhancements:
Purpose: Evaluate current story quality against definition of ready.
Actions:
Read story file from .claude/stories/{story-id}.md
Parse story components:
Assess quality against definition of ready (INVEST):
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.
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:
Clarify Action:
Articulate Value:
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
Purpose: Define specific, testable criteria for "done".
AC Best Practices:
AC Categories to Cover:
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.
Purpose: Anticipate boundary conditions, unusual inputs, and failure scenarios.
Edge Case Categories:
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.
Purpose: Provide technical context for implementation.
Technical Notes Structure:
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.
Purpose: Define how to verify story works correctly.
Test Types:
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.
Purpose: Ensure story fits in one sprint (≤13 points).
Size Categories:
Splitting Triggers:
Splitting Strategies:
Reference: See refinement-techniques.md for detailed splitting strategies.
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.
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
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
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
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 planimplement-feature → Implement with clear guidanceRefine 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
Detailed documentation in references/: