메뉴
Pre-implementation story validation with 10-step comprehensive assessment including template compliance, anti-hallucination verification, and implementation readiness scoring. This skill should be used before handing story to development agent.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | validate-story |
| description | Pre-implementation story validation with 10-step comprehensive assessment including template compliance, anti-hallucination verification, and implementation readiness scoring. This skill should be used before handing story to development agent. |
| acceptance | [{"validation_complete":"All 10 validation steps executed successfully"},{"go_no_go_decision":"Clear GO or NO-GO decision with confidence level"},{"report_generated":"Validation report created with findings and recommendations"},{"critical_issues_identified":"All blocking issues identified and documented"}] |
| inputs | {"story_file":{"type":"string","required":true,"description":"Path to story file in .claude/stories/{epic-id}/{story-id}.md format"},"validation_mode":{"type":"enum","values":["full","quick","critical_only"],"default":"full","description":"Validation depth: full (all 10 steps), quick (critical steps only), critical_only (blocking issues)"}} |
| outputs | {"validation_passed":{"type":"boolean","description":"GO (true) or NO-GO (false) decision"},"readiness_score":{"type":"number","description":"Implementation readiness score (1-10)"},"confidence_level":{"type":"enum","values":["High","Medium","Low"],"description":"Confidence in successful implementation"},"critical_issues":{"type":"array","description":"Must-fix issues blocking implementation"},"should_fix_issues":{"type":"array","description":"Important quality improvements (recommended)"},"nice_to_have":{"type":"array","description":"Optional enhancements"},"anti_hallucination_findings":{"type":"array","description":"Unverifiable claims or invented details"}} |
| telemetry | {"emit":"skill.validate-story.completed","track":["story_id","validation_passed","readiness_score","confidence_level","critical_issues_count","should_fix_count","anti_hallucination_count","duration_ms"]} |
Pre-implementation story validation with comprehensive 10-step assessment to catch issues before development begins.
Before handing a story to James (Developer Agent), validate that the story is complete, accurate, and implementable. Catch template gaps, hallucinated details, and missing context that would cause implementation failures.
Core Principles:
Integration:
This skill should be used when:
This skill should NOT be used when:
.claude/stories/{epic-id}/{story-id}.mdPurpose: Load project configuration, story file, template, and related documents.
Actions:
Load Story File:
Use Claude Code Read tool:
Read: .claude/stories/{epic-id}/{story-id}.md
Extract metadata:
Load Story Template:
Read: .claude/skills/planning/create-story/references/templates.md
Extract template structure:
Load Parent Epic (if applicable):
If story references epic:
Read: .claude/epics/{epic-id}.md
Verify story aligns with epic objectives.
Load Project Structure:
Read: docs/unified-project-structure.md
For validating file paths and directory structure.
Load Architecture Docs (for anti-hallucination):
Read: docs/architecture/*.md
For verifying technical claims.
Outputs:
story_content - Full story texttemplate_sections[] - Required sections from templateepic_context - Parent epic detailsproject_structure - Expected file/directory layoutarchitecture_docs[] - Technical reference docsSee: references/templates.md for story template structure
Purpose: Ensure all required template sections present and no unfilled placeholders.
Actions:
Extract Story Sections:
Parse story markdown to extract sections:
Compare with Template:
For each required section in template:
Check for Unfilled Placeholders:
Search for placeholder patterns:
{{EpicNum}}, {{StoryNum}}, {{var}}_TBD_, [TBD], TODO..., [more details needed]Report Missing/Incomplete Sections:
Critical Issues:
- Missing section: "Testing & Validation"
- Unfilled placeholder: {{EpicNum}} in Objective
- Empty section: "Dependencies"
Should-Fix:
- Section "Dev Notes" has only 2 lines (expected detailed technical context)
Validation Criteria:
{{var}}, _TBD_)Outputs:
missing_sections[] - Required sections not foundunfilled_placeholders[] - Placeholder patterns still in storyempty_sections[] - Sections with no/minimal contentSee: references/validation-checklist.md for detailed template requirements
Purpose: Verify file paths, directory structure, and source tree references are accurate and consistent.
Actions:
Extract File References:
From story sections (File List, Tasks, Dev Notes):
Validate File Paths:
For each file path:
Check Directory Consistency:
Verify Source Tree References:
If story mentions project structure:
docs/unified-project-structure.mdReport File Structure Issues:
Critical Issues:
- File path uses Windows separators: "src\auth\login.ts" (should be "src/auth/login.ts")
- Referenced directory doesn't exist: "src/services/auth/" (project has "src/auth/")
Should-Fix:
- Test file in source directory: "src/api/user.test.ts" (should be "tests/api/user.test.ts")
Validation Criteria:
Outputs:
invalid_paths[] - File paths that don't match project structureinconsistent_dirs[] - Directory naming issuesfile_location_issues[] - Files in wrong locationsSee: references/validation-checklist.md for file structure rules
Purpose: For frontend/UI stories, ensure design, components, and interactions are fully specified.
Actions:
Detect UI Story:
Check if story involves frontend:
.tsx, .vue, .jsx, .html, .cssIf UI Story, Validate:
Component Specifications:
Styling/Design:
User Interactions:
Frontend-Backend Integration:
Report UI Completeness Issues:
Critical Issues:
- No responsive design guidance (mobile/tablet behavior undefined)
Should-Fix:
- Missing accessibility requirements (ARIA labels, keyboard navigation)
- Form validation rules not specified
Validation Criteria (for UI stories):
Outputs:
ui_component_issues[] - Component specification gapsui_design_issues[] - Design/styling gapsui_interaction_issues[] - User flow gapsSee: references/validation-checklist.md for UI validation details
Purpose: Ensure tasks will actually satisfy all acceptance criteria when implemented.
Actions:
Extract Acceptance Criteria:
From story "Acceptance Criteria" section:
Extract Tasks:
From story "Tasks/Subtasks" section:
Map Tasks to ACs:
For each AC:
Identify Gaps:
Coverage Analysis:
AC1 "User can log in" → Task 1.1, Task 1.2 ✅
AC2 "Password reset works" → Task 2.1 ✅
AC3 "Session timeout" → No tasks found ❌
Gaps:
- AC3 has no implementing tasks
- AC4 partially covered (only happy path, no error cases)
Verify AC Testability:
For each AC:
Report AC Issues:
Critical Issues:
- AC3 "Session timeout" has no implementing tasks
- AC5 too vague: "System should be secure" (not measurable)
Should-Fix:
- AC2 missing error case testing
- AC4 missing edge case handling
Validation Criteria:
Outputs:
uncovered_acs[] - ACs with no implementing taskspartial_coverage_acs[] - ACs partially coveredvague_acs[] - ACs not measurable/testableSee: references/validation-checklist.md for AC validation rules
Purpose: Ensure testing approach is clear and comprehensive.
Actions:
Extract Testing Section:
From "Testing & Validation" section:
Validate Test Approach:
Check Test Coverage:
For each AC:
Verify Test Data Requirements:
Report Testing Issues:
Critical Issues:
- No test scenarios for AC3
- Testing section says "test manually" (not specific)
Should-Fix:
- Missing integration test scenarios
- No test data requirements specified
Validation Criteria:
Outputs:
missing_test_scenarios[] - ACs without test scenariosvague_testing[] - Non-specific testing instructionstest_data_gaps[] - Missing test data requirementsSee: references/validation-checklist.md for testing validation
Purpose: For security-critical stories, ensure security requirements are identified and addressed.
Actions:
Detect Security-Critical Story:
Keywords: "auth", "password", "token", "encryption", "secure", "permission", "access control"
If Security-Critical, Validate:
Security Requirements:
Compliance:
Report Security Issues:
Critical Issues:
- Story involves password storage but no hashing requirements specified
- No input validation mentioned for user registration
Should-Fix:
- Missing rate limiting requirements
- No mention of HTTPS enforcement
Validation Criteria (for security stories):
Outputs:
security_gaps[] - Missing security requirementscompliance_issues[] - Compliance gapsSee: references/validation-checklist.md for security validation
Purpose: Ensure tasks are in logical order with clear dependencies.
Actions:
Extract Task Sequence:
From "Tasks/Subtasks":
Validate Logical Order:
Check Task Granularity:
Verify Completeness:
Report Task Sequence Issues:
Critical Issues:
- Task 3 depends on Task 5 (circular dependency)
- Task 2 "Implement controller" before Task 1 "Create model" (wrong order)
Should-Fix:
- Task granularity too broad: "Implement entire auth system" (break down)
- Missing task: "Add integration tests" (not in task list)
Validation Criteria:
Outputs:
task_order_issues[] - Tasks in wrong ordertask_dependency_issues[] - Circular or unclear dependenciestask_granularity_issues[] - Tasks too broad or too fineSee: references/validation-checklist.md for task validation
Purpose: Verify all technical claims are traceable to source documents, not invented.
Actions:
Extract Technical Claims:
From story (Dev Notes, Tasks, File List):
Verify Against Sources:
File/Directory Claims:
docs/unified-project-structure.mdLibrary/Framework Claims:
package.json, requirements.txt, architecture docsAPI Endpoint Claims:
docs/architecture/api-spec.mdDatabase Claims:
docs/architecture/database-schema.mdArchitecture Pattern Claims:
docs/architecture/ docsIdentify Hallucinations:
Anti-Hallucination Findings:
Critical:
- Story claims "bcrypt library" but not in package.json dependencies
- References "auth-service.ts" but no such file in project structure
- Mentions "Redis cache" but architecture docs don't specify Redis
Should-Fix:
- Claims "JWT authentication" but architecture uses sessions
- References "/api/users" endpoint not in API spec
Flag Unverifiable Claims:
Validation Criteria:
Outputs:
hallucinated_files[] - Files/dirs not in projecthallucinated_libs[] - Libraries not in dependencieshallucinated_apis[] - API endpoints not documentedhallucinated_patterns[] - Patterns not in architectureSee: references/validation-checklist.md for anti-hallucination checks
Purpose: Assess if story provides sufficient context for developer agent to implement without external docs.
Actions:
Check Self-Contained Context:
Verify Clear Instructions:
Assess Complete Technical Context:
From Dev Notes:
Identify Missing Information:
Implementation Readiness Issues:
Critical:
- Dev Notes missing: No technical approach specified
- Vague task: "Implement authentication" (which method? OAuth? JWT? Sessions?)
Should-Fix:
- Missing integration details: How does this connect to existing auth system?
- No error handling guidance
Score Implementation Readiness:
Readiness Score (1-10):
Validation Criteria:
Outputs:
readiness_score - Score 1-10missing_context[] - Missing technical detailsvague_instructions[] - Ambiguous tasksexternal_refs_needed[] - References to external docs requiredSee: references/validation-checklist.md for readiness assessment
Purpose: Synthesize all validation findings into actionable report with GO/NO-GO decision.
Actions:
Categorize Issues:
Critical Issues (Must Fix - Story Blocked):
Should-Fix Issues (Important Quality):
Nice-to-Have (Optional Enhancements):
Calculate Readiness Score:
Readiness Score Calculation:
Base: 10 points
Deductions:
- Critical issues: -2 points each
- Should-fix issues: -0.5 points each
- Anti-hallucination findings: -1 point each
Score = max(1, 10 - total_deductions)
Determine Confidence Level:
Make GO/NO-GO Decision:
GO Criteria:
NO-GO Criteria:
2 critical issues, OR
Generate Report:
# Story Validation Report
**Story:** {epic-id}/{story-id} - {title}
**Validated:** {date}
**Validator:** validate-story skill
## Summary
**Decision:** GO / NO-GO
**Readiness Score:** {score}/10
**Confidence Level:** High / Medium / Low
## Validation Results
### Template Compliance: ✅ PASS / ❌ FAIL
- All required sections present
- No unfilled placeholders
### File Structure: ✅ PASS / ⚠️ CONCERNS / ❌ FAIL
- File paths match project structure
- Consistent directory naming
[... continue for all 10 validation steps ...]
## Critical Issues (Must Fix): {count}
1. [SECTION] Description
- Location: {section name or line number}
- Fix: {how to fix}
## Should-Fix Issues (Recommended): {count}
1. [SECTION] Description
- Recommendation: {how to improve}
## Anti-Hallucination Findings: {count}
1. Claim "{detail}" not verified in {source}
- Fix: Remove or source from architecture docs
## Recommendation
{GO/NO-GO} - {rationale}
{If NO-GO}: Fix {count} critical issues before handing to James.
{If GO}: Proceed to implementation. Address {count} should-fix issues during development.
## Next Steps
{If GO}:
- Hand to James: @james *implement {story-id}
- Monitor for should-fix issues during implementation
{If NO-GO}:
1. Fix critical issues listed above
2. Re-validate: @validate-story {story-file}
3. Proceed once validation passes
Outputs:
validation_report - Full markdown reportvalidation_passed - Boolean GO/NO-GOreadiness_score - Number 1-10confidence_level - High/Medium/Lowcritical_issues[], should_fix_issues[], nice_to_have[]See: references/templates.md for full report template
Skill complete when:
Story Creation → Validation → Implementation Flow:
# Step 1: Create story
@create-story epic-001 story-003 "User Authentication"
# Step 2: Validate story
@validate-story .claude/stories/epic-001/story-003.md
# If GO:
@james *implement story-003
# If NO-GO:
# Fix critical issues, re-validate
@validate-story .claude/stories/epic-001/story-003.md
Who Invokes:
Escalate to user when:
references/templates.md - Validation report format, story template schemareferences/validation-checklist.md - Detailed checklist for all 10 stepsreferences/examples.md - GO and NO-GO validation examplesPart of BMAD Enhanced Planning Suite - Ensures quality stories before implementation
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.
Atomic command primitives for BMAD operations. Provides type-safe, testable wrappers around file operations and test execution with structured JSON I/O and built-in telemetry. This skill should be used when BMAD workflows need deterministic, reliable primitive operations with observability.
Break down epics into implementable user stories with acceptance criteria, estimates, dependencies, and sprint groupings. This skill should be used for epic planning and backlog grooming.
Generate and compare multiple architecture options (minimal, moderate, full modernization) with comprehensive trade-offs analysis across cost, timeline, risk, performance, and maintainability dimensions. Use when evaluating multiple architectural approaches or deciding between modernization strategies with different cost/risk trade-offs.