# User Flow Validation Checklist ## Quick Start Validation Template Use this checklist to validate any user flow before implementation. Copy and customize for each flow. --- ## Flow: ________________________________ **File**: `planning/[freelancer|developer|api_customer]_flows.toml` **Reviewer**: ________________________________ **Date**: ________________________________ --- ## ✅ Section 1: Basic Structure Validation ### User Story Mapping - [ ] **Story Reference Exists**: Flow has `[flow.{id}.user_story]` section - [ ] **Story ID Valid**: `story_id` exists in the referenced `story_document` - [ ] **Story Document Exists**: Referenced `.md` file exists and is accessible - [ ] **Actor Consistency**: Flow `actor` matches user story target user - [ ] **Story Title Match**: `story_title` accurately reflects the referenced story ### Flow Definition Completeness - [ ] **Required Fields Present**: `id`, `name`, `type`, `actor`, `trigger`, `description` all populated - [ ] **Type Validity**: `type` is either "atomic" or "composed" - [ ] **Unique ID**: Flow `id` is unique across all flow files - [ ] **Clear Trigger**: `trigger` describes specific, actionable condition - [ ] **Descriptive Name**: `name` clearly indicates the flow purpose --- ## ✅ Section 2: Dependencies and Prerequisites ### System Dependencies - [ ] **Systems Listed**: All required systems listed in `dependencies.systems` - [ ] **System Documentation**: Each system has corresponding API/integration documentation - [ ] **API Endpoints Documented**: All `integrations.apis` have complete documentation - [ ] **Service Dependencies Clear**: Prerequisites specify exactly what must be ready ### State Management - [ ] **Required States Defined**: `dependencies.states` lists all necessary preconditions - [ ] **State Transitions Clear**: Flow clearly shows how states change - [ ] **Prerequisites Actionable**: Each prerequisite can be verified before flow execution --- ## ✅ Section 3: Success Criteria and Error Handling ### Success Definition - [ ] **Primary Success Clear**: `success_criteria.primary` is specific and measurable - [ ] **Secondary Criteria Listed**: All important outcomes captured in `secondary` array - [ ] **Acceptance Criteria Alignment**: Success criteria align with user story acceptance criteria - [ ] **Measurable Outcomes**: Success can be objectively verified ### Error Scenarios - [ ] **Common Errors Covered**: All likely error conditions included in `error_handling` - [ ] **Error Responses Actionable**: Each error condition has clear resolution path - [ ] **Error Recovery Documented**: Users understand how to recover from failures - [ ] **Graceful Degradation**: System handles errors without data loss --- ## ✅ Section 4: Implementation Guidance ### Step Documentation **For Atomic Flows:** - [ ] **All Steps Documented**: Each `[[flow.steps]]` has implementation guidance - [ ] **Step Sequence Logical**: Order makes sense and enables success - [ ] **Actor Assignment Clear**: Each step specifies who performs the action - [ ] **System Interactions Specified**: `system_interaction` identifies exact components - [ ] **Validation Rules Present**: Steps requiring validation have clear criteria **For Composed Flows:** - [ ] **Phase Organization Clear**: `[[flow.composed_steps]]` logically group atomic flows - [ ] **Atomic Flow References Valid**: All referenced `atomic_flows` exist - [ ] **Phase Dependencies Understood**: Prerequisites between phases are clear - [ ] **End-to-End Coherence**: Complete journey makes business sense ### Business Rules - [ ] **Constraints Implementable**: All `business_rules.constraints` can be enforced - [ ] **Validations Testable**: All `business_rules.validations` can be automated - [ ] **Permissions Defined**: Required `business_rules.permissions` are specified - [ ] **Rule Consistency**: Business rules align across related flows --- ## ✅ Section 5: Testing and Quality Assurance ### Test Coverage - [ ] **Happy Path Testable**: Primary success scenario can be automated - [ ] **Error Path Testable**: Each error condition can be triggered and tested - [ ] **Edge Cases Identified**: Boundary conditions and unusual scenarios considered - [ ] **Performance Testable**: `metrics.time_target` and `success_rate_target` are measurable ### Quality Standards - [ ] **User Experience Coherent**: Flow provides good user experience - [ ] **Technical Feasibility Confirmed**: All steps are technically possible - [ ] **Security Considerations**: Flow doesn't introduce security vulnerabilities - [ ] **Accessibility Compliant**: Flow works for users with disabilities --- ## ✅ Section 6: Documentation Quality ### Implementation Documentation - [ ] **Developer Guide Exists**: Step-by-step implementation instructions available - [ ] **API Examples Provided**: Code examples for all system integrations - [ ] **Configuration Guide Present**: Setup instructions for required systems - [ ] **Troubleshooting Guide Available**: Common issues and resolutions documented ### User Documentation - [ ] **User Guide Exists**: End-user instructions for flow completion - [ ] **Screenshots/Mockups Present**: Visual guidance for UI interactions - [ ] **Help Content Available**: Context-sensitive help for each step - [ ] **Error Message Documentation**: Clear error messages and recovery instructions --- ## ✅ Section 7: Cross-Reference Validation ### Flow Relationships - [ ] **Related Flows Identified**: Connections to other flows documented - [ ] **Flow Dependencies Clear**: Prerequisites from other flows specified - [ ] **Integration Points Mapped**: How this flow connects to broader system - [ ] **Data Flow Traced**: Information flow between steps and systems ### Documentation Cross-References - [ ] **Story Links Work**: References to user stories are valid - [ ] **API Links Work**: References to API documentation are current - [ ] **Internal Links Valid**: All cross-references within documentation work - [ ] **External Dependencies Current**: Third-party documentation references are up-to-date --- ## 📊 Validation Results Summary ### Coverage Score - **Structure**: ___/15 items completed - **Dependencies**: ___/8 items completed - **Success/Error**: ___/8 items completed - **Implementation**: ___/12 items completed - **Testing**: ___/8 items completed - **Documentation**: ___/8 items completed - **Cross-Reference**: ___/8 items completed **Overall Score**: ___/67 (Minimum 90% required for implementation approval) ### Priority Issues Found **High Priority (Must Fix Before Implementation):** 1. ________________________________ 2. ________________________________ 3. ________________________________ **Medium Priority (Fix During Implementation):** 1. ________________________________ 2. ________________________________ **Low Priority (Address in Next Iteration):** 1. ________________________________ 2. ________________________________ --- ## 🎯 Validation Decision ### Implementation Readiness - [ ] **APPROVED**: Flow is ready for implementation (≥90% validation score) - [ ] **CONDITIONAL**: Flow needs minor fixes before implementation (80-89%) - [ ] **REJECTED**: Flow needs major work before implementation (<80%) ### Next Steps **If Approved:** - [ ] Add to implementation backlog - [ ] Assign to development team - [ ] Schedule implementation review **If Conditional:** - [ ] Address priority issues - [ ] Re-run validation - [ ] Update documentation **If Rejected:** - [ ] Major revision required - [ ] Stakeholder review needed - [ ] Re-design flow components ### Sign-Off **Product Owner**: ________________________________ **Date**: ________ **Tech Lead**: ________________________________ **Date**: ________ **QA Lead**: ________________________________ **Date**: ________ --- ## 🔄 Validation History | Date | Reviewer | Score | Status | Notes | |------|----------|-------|--------|--------| | | | | | | | | | | | | | | | | | | --- ## 📋 Quick Reference: Common Validation Issues ### Typical Structure Problems - Missing user story mapping - Vague or untestable success criteria - Incomplete error handling scenarios - Missing system dependencies ### Typical Implementation Problems - Steps lacking technical detail - Unrealistic time targets - Missing validation rules - Undefined system interactions ### Typical Documentation Problems - Broken cross-references - Outdated API documentation - Missing user guidance - Incomplete troubleshooting guides ### Quick Fixes - **Missing References**: Update TOML with correct story IDs and documents - **Broken Links**: Verify all documentation exists and is accessible - **Vague Steps**: Add specific technical details and system interactions - **Missing Errors**: Review common failure modes and add error handling --- *Use this checklist for every flow before implementation to ensure complete, accurate, and actionable documentation.*