sf-agent-framework

# Story Context Validator ## Purpose Validate that implementation stories contain complete context for lean development phase. ## Validation Criteria ### 1. Business Context Completeness - [ ] Business problem clearly stated - [ ] User personas identified - [ ] Success metrics defined - [ ] Business value/ROI explained - [ ] Compliance requirements listed (if applicable) ### 2. Functional Requirements - [ ] User story in proper format - [ ] Acceptance criteria comprehensive - [ ] Edge cases covered - [ ] Performance requirements specified - [ ] Security requirements defined - [ ] Out of scope items listed ### 3. Technical Context - [ ] Architecture excerpt included (not referenced) - [ ] Data model complete with field types - [ ] Object relationships defined - [ ] Integration endpoints specified - [ ] API payloads provided with examples - [ ] Security model detailed ### 4. Implementation Specifications - [ ] Apex class structures defined - [ ] Method signatures provided - [ ] LWC component structure detailed - [ ] Configuration requirements listed - [ ] Validation rules specified - [ ] Process automation defined ### 5. Implementation Steps - [ ] Sequential steps numbered - [ ] Commands provided where needed - [ ] Code snippets included - [ ] Configuration steps detailed - [ ] No external references ### 6. Testing Requirements - [ ] Test methods named - [ ] Test scenarios described - [ ] Test data specified - [ ] Coverage requirements stated - [ ] Bulk test requirements included ### 7. Deployment Information - [ ] Package.xml components listed - [ ] Deployment order specified - [ ] Rollback plan provided - [ ] Dependencies identified ## Validation Process ### Step 1: Structure Check Verify all required sections present: ```yaml required_sections: - story_metadata - business_context - functional_requirements - technical_context - implementation_specifications - implementation_steps - validation_testing - deployment_readiness ``` ### Step 2: Content Depth Check Ensure sections contain substance, not placeholders: ```yaml minimum_content_length: business_context: 200_chars technical_context: 500_chars implementation_specs: 300_chars implementation_steps: 400_chars ``` ### Step 3: Reference Check Scan for external references that should be inline: ```yaml forbidden_patterns: - 'see architecture document' - 'refer to requirements' - 'check with architect' - 'TBD' - 'TODO' - '[placeholder]' - '<<insert here>>' ``` ### Step 4: Completeness Score Calculate story completeness: ```yaml scoring: structure: 30% business_context: 15% technical_context: 25% implementation_detail: 20% testing_coverage: 10% minimum_passing_score: 85% ``` ## Validation Rules ### MUST HAVE (Blocking) 1. **Story ID and metadata** - Cannot proceed without identification 2. **Acceptance criteria** - Must know what defines "done" 3. **Technical specifications** - Must know what to build 4. **Implementation steps** - Must know how to build ### SHOULD HAVE (Warning) 1. **Test specifications** - Important but can be derived 2. **Performance requirements** - Should be explicit 3. **Security considerations** - Should be documented 4. **Deployment components** - Should be listed ### NICE TO HAVE (Info) 1. **Code examples** - Helpful but not mandatory 2. **API response examples** - Useful for integration 3. **Error handling details** - Good to have upfront 4. **Rollback procedures** - Important for production ## Validation Output ### Pass Example ```yaml validation_result: story_id: STORY-001-001 status: PASSED score: 92% sections_present: 8/8 content_depth: GOOD external_references: 0 warnings: - 'Performance benchmarks could be more specific' ready_for_development: true ``` ### Fail Example ```yaml validation_result: story_id: STORY-001-002 status: FAILED score: 68% sections_present: 6/8 content_depth: INSUFFICIENT external_references: 3 errors: - 'Missing technical context section' - 'Implementation steps too vague' - "External reference: 'see data model document'" warnings: - 'Test coverage requirement not specified' - 'No deployment order provided' ready_for_development: false required_actions: - 'Add complete data model inline' - 'Provide step-by-step implementation guide' - 'Replace external references with actual content' ``` ## Auto-Fix Suggestions ### For Missing Business Context ```markdown Add: ## Business Context **Problem**: [What problem does this solve?] **Users**: [Who will use this feature?] **Value**: [What value does it provide?] **Success**: [How is success measured?] ``` ### For Incomplete Technical Context ```markdown Add: ## Technical Context ### Data Model **Object**: [Name] - Field: [Name] ([Type], [Required?]) - Relationship: [Field] ([Type] to [Object]) ### Integration **System**: [Name] **Endpoint**: [URL] **Method**: [GET/POST/PUT/DELETE] **Auth**: [Type] ``` ### For Vague Implementation Steps ````markdown Replace vague steps with specific ones: Instead of: "Create Apex class" Use: 1. Navigate to force-app/main/default/classes/ 2. Create file ProjectService.cls 3. Add class structure: ```apex public with sharing class ProjectService { ``` ```` 4. Implement methods as specified above ```` ## Validation Automation ### Command Line Usage ```bash # Validate single story sfa validate-story STORY-001-001 # Validate all stories in queue sfa validate-queue # Validate with auto-fix suggestions sfa validate-story STORY-001-001 --suggest-fixes # Validate and block invalid stories sfa validate-queue --block-invalid ```` ### Programmatic Usage ```javascript const validator = new StoryValidator(); const result = await validator.validateStory('STORY-001-001'); if (!result.passed) { console.log('Story needs enrichment:'); result.errors.forEach((error) => console.log(`- ${error}`)); if (result.autoFixAvailable) { await validator.applyAutoFix(storyId); } } ``` ## Best Practices ### DO: - ✅ Run validation before starting development - ✅ Fix all errors before marking story ready - ✅ Address warnings when possible - ✅ Re-validate after story updates - ✅ Use auto-fix for common issues ### DON'T: - ❌ Skip validation to save time - ❌ Ignore warnings repeatedly - ❌ Start development with failed validation - ❌ Assume context is complete without checking ## Success Metrics Well-validated stories result in: - **90% fewer** context-related questions during development - **75% reduction** in development blocking issues - **85% first-pass** implementation accuracy - **50% faster** story completion time ## Integration with Workflow ```yaml workflow_integration: - phase: transition action: validate_generated_stories blocking: true - phase: development action: validate_before_assignment blocking: true - phase: development action: validate_after_completion blocking: false ```