checklist standardization and improvement with llm eliciatation

bmad-core/checklists/brownfield-checklist.md

@@ -0,0 +1,480 @@
+# Brownfield Enhancement Validation Checklist
+
+This checklist serves as a comprehensive framework for Product Owners to validate brownfield enhancements before development execution. It ensures thorough analysis of existing systems, proper integration planning, and risk mitigation for working with existing codebases.
+
+[[LLM: CRITICAL INITIALIZATION - BROWNFIELD CONTEXT
+
+This checklist requires extensive access to the existing project. Before proceeding, ensure you have:
+
+1. brownfield-prd.md - The brownfield product requirements (check docs/brownfield-prd.md)
+2. brownfield-architecture.md - The enhancement architecture (check docs/brownfield-architecture.md)
+3. Existing Project Access:
+
+   - Full source code repository access
+   - Current deployment configuration
+   - Database schemas and data models
+   - API documentation (internal and external)
+   - Infrastructure configuration
+   - CI/CD pipeline configuration
+   - Current monitoring/logging setup
+
+4. Optional but Valuable:
+   - existing-project-docs.md
+   - tech-stack.md with version details
+   - source-tree.md or actual file structure
+   - Performance benchmarks
+   - Known issues/bug tracker access
+   - Team documentation/wikis
+
+IMPORTANT: If you don't have access to the existing project codebase, STOP and request access. Brownfield validation cannot be properly completed without examining the actual system being enhanced.
+
+CRITICAL MINDSET: You are validating changes to a LIVE SYSTEM. Every decision has the potential to break existing functionality. Approach this with:
+
+1. Extreme Caution - Assume every change could have unintended consequences
+2. Deep Investigation - Don't trust documentation alone, verify against actual code
+3. Integration Focus - The seams between new and old are where failures occur
+4. User Impact - Existing users depend on current functionality, preserve their workflows
+5. Technical Debt Awareness - Understand what compromises exist and why
+
+EXECUTION MODE:
+Ask the user if they want to work through the checklist:
+
+- Section by section (interactive mode) - Review each section, present findings, get confirmation before proceeding
+- All at once (comprehensive mode) - Complete full analysis and present comprehensive report at end]]
+
+## 1. EXISTING PROJECT ANALYSIS VALIDATION
+
+[[LLM: Begin by conducting a thorough investigation of the existing system. Don't just read documentation - examine actual code, configuration files, and deployment scripts. Look for:
+
+- Undocumented behaviors that users might depend on
+- Technical debt that could complicate integration
+- Patterns and conventions that new code must follow
+- Hidden dependencies not mentioned in documentation
+
+As you validate each item below, cite specific files, code sections, or configuration details as evidence. For each check, provide specific examples from the codebase.]]
+
+### 1.1 Project Documentation Completeness
+
+- [ ] All required existing project documentation has been located and analyzed
+- [ ] Tech stack documentation is current and accurate
+- [ ] Source tree/architecture overview exists and is up-to-date
+- [ ] Coding standards documentation reflects actual codebase practices
+- [ ] API documentation exists and covers all active endpoints
+- [ ] External API integrations are documented with current versions
+- [ ] UX/UI guidelines exist and match current implementation
+- [ ] Any missing documentation has been identified and creation planned
+
+### 1.2 Existing System Understanding
+
+- [ ] Current project purpose and core functionality clearly understood
+- [ ] Existing technology stack versions accurately identified
+- [ ] Current architecture patterns and conventions documented
+- [ ] Existing deployment and infrastructure setup analyzed
+- [ ] Performance characteristics and constraints identified
+- [ ] Security measures and compliance requirements documented
+- [ ] Known technical debt and limitation areas identified
+- [ ] Active maintenance and support processes understood
+
+### 1.3 Codebase Analysis Quality
+
+- [ ] File structure and organization patterns documented
+- [ ] Naming conventions and coding patterns identified
+- [ ] Testing frameworks and patterns analyzed
+- [ ] Build and deployment processes understood
+- [ ] Dependency management approach documented
+- [ ] Configuration management patterns identified
+- [ ] Error handling and logging patterns documented
+- [ ] Integration points with external systems mapped
+
+## 2. ENHANCEMENT SCOPE VALIDATION
+
+[[LLM: The scope determines everything. Before validating, answer: Is this enhancement truly significant enough to warrant this comprehensive process, or would a simpler approach suffice? Consider:
+
+- Could this be done as a simple feature addition?
+- Are we over-engineering the solution?
+- What's the minimum viable change that delivers value?
+- Are we addressing the root cause or just symptoms?
+
+Be prepared to recommend a simpler approach if the current plan is overkill. If the enhancement could be done in 1-2 stories, suggest using brownfield-create-epic or brownfield-create-story instead.]]
+
+### 2.1 Complexity Assessment
+
+- [ ] Enhancement complexity properly assessed (significant vs. simple)
+- [ ] Scope justifies full PRD/Architecture process vs. simple epic/story creation
+- [ ] Enhancement type clearly categorized (new feature, modification, integration, etc.)
+- [ ] Impact assessment on existing codebase accurately evaluated
+- [ ] Resource requirements appropriate for enhancement scope
+- [ ] Timeline expectations realistic given existing system constraints
+- [ ] Success criteria defined and measurable
+- [ ] Rollback criteria and thresholds established
+
+### 2.2 Integration Points Analysis
+
+- [ ] All integration points with existing system identified
+- [ ] Data flow between new and existing components mapped
+- [ ] API integration requirements clearly defined
+- [ ] Database schema integration approach specified
+- [ ] UI/UX integration requirements documented
+- [ ] Authentication/authorization integration planned
+- [ ] External service integration impacts assessed
+- [ ] Performance impact on existing system evaluated
+
+### 2.3 Compatibility Requirements
+
+- [ ] Existing API compatibility requirements defined
+- [ ] Database schema backward compatibility ensured
+- [ ] UI/UX consistency requirements specified
+- [ ] Integration compatibility with existing workflows maintained
+- [ ] Third-party service compatibility verified
+- [ ] Browser/platform compatibility requirements unchanged
+- [ ] Performance compatibility maintained or improved
+- [ ] Security posture maintained or enhanced
+
+## 3. RISK ASSESSMENT AND MITIGATION
+
+[[LLM: This is the most critical section. Think like a pessimist - what's the worst that could happen? For each risk:
+
+1. Identify specific code/configuration that could break
+2. Trace the potential cascade of failures
+3. Quantify the user impact (how many affected, how severely)
+4. Validate that mitigation strategies are concrete, not theoretical
+
+Remember: In production, Murphy's Law is gospel. If it can fail, it will fail. For each risk identified, cite specific code locations and estimate blast radius.]]
+
+### 3.1 Technical Risk Evaluation
+
+- [ ] Risk of breaking existing functionality assessed
+- [ ] Database migration risks identified and mitigated
+- [ ] API breaking change risks evaluated
+- [ ] Deployment risks to existing system assessed
+- [ ] Performance degradation risks identified
+- [ ] Security vulnerability risks evaluated
+- [ ] Third-party service integration risks assessed
+- [ ] Data loss or corruption risks mitigated
+
+### 3.2 Mitigation Strategy Completeness
+
+- [ ] Rollback procedures clearly defined and tested
+- [ ] Feature flag strategy implemented for gradual rollout
+- [ ] Backup and recovery procedures updated
+- [ ] Monitoring and alerting enhanced for new components
+- [ ] Performance testing strategy includes existing functionality
+- [ ] Security testing covers integration points
+- [ ] User communication plan for changes prepared
+- [ ] Support team training plan developed
+
+### 3.3 Testing Strategy Validation
+
+- [ ] Regression testing strategy covers all existing functionality
+- [ ] Integration testing plan validates new-to-existing connections
+- [ ] Performance testing includes existing system baseline
+- [ ] Security testing covers enhanced attack surface
+- [ ] User acceptance testing includes existing workflows
+- [ ] Load testing validates system under enhanced load
+- [ ] Disaster recovery testing updated for new components
+- [ ] Automated test suite extended appropriately
+
+## 4. ARCHITECTURE INTEGRATION VALIDATION
+
+[[LLM: Architecture mismatches are subtle but deadly. As you review integration points:
+
+1. Compare actual code patterns with proposed patterns - do they clash?
+2. Check version compatibility down to patch levels
+3. Verify assumptions about existing system behavior
+4. Look for impedance mismatches in data models, API styles, error handling
+5. Consider performance implications of integration overhead
+
+If you find architectural incompatibilities, flag them as CRITICAL issues. Provide specific examples of pattern conflicts.]]
+
+### 4.1 Technology Stack Alignment
+
+- [ ] New technologies justified and compatible with existing stack
+- [ ] Version compatibility verified across all dependencies
+- [ ] Build process integration validated
+- [ ] Deployment pipeline integration planned
+- [ ] Configuration management approach consistent
+- [ ] Monitoring and logging integration maintained
+- [ ] Security tools and processes integration verified
+- [ ] Development environment setup updated appropriately
+
+### 4.2 Component Integration Design
+
+- [ ] New components follow existing architectural patterns
+- [ ] Component boundaries respect existing system design
+- [ ] Data models integrate properly with existing schema
+- [ ] API design consistent with existing endpoints
+- [ ] Error handling consistent with existing patterns
+- [ ] Authentication/authorization integration seamless
+- [ ] Caching strategy compatible with existing approach
+- [ ] Service communication patterns maintained
+
+### 4.3 Code Organization Validation
+
+- [ ] New code follows existing project structure conventions
+- [ ] File naming patterns consistent with existing codebase
+- [ ] Import/export patterns match existing conventions
+- [ ] Testing file organization follows existing patterns
+- [ ] Documentation approach consistent with existing standards
+- [ ] Configuration file patterns maintained
+- [ ] Asset organization follows existing conventions
+- [ ] Build output organization unchanged
+
+## 5. IMPLEMENTATION PLANNING VALIDATION
+
+[[LLM: Implementation sequence can make or break a brownfield project. Review the plan with these questions:
+
+- Can each story be deployed without breaking existing functionality?
+- Are there hidden dependencies between stories?
+- Is there a clear rollback point for each story?
+- Will users experience degraded service during any phase?
+- Are we testing the integration points sufficiently at each step?
+
+Pay special attention to data migrations - they're often the source of catastrophic failures. For each story, verify it maintains system integrity.]]
+
+### 5.1 Story Sequencing Validation
+
+- [ ] Stories properly sequenced to minimize risk to existing system
+- [ ] Each story maintains existing functionality integrity
+- [ ] Story dependencies clearly identified and logical
+- [ ] Rollback points defined for each story
+- [ ] Integration verification included in each story
+- [ ] Performance impact assessment included per story
+- [ ] User impact minimized through story sequencing
+- [ ] Value delivery incremental and testable
+
+### 5.2 Development Approach Validation
+
+- [ ] Development environment setup preserves existing functionality
+- [ ] Local testing approach validated for existing features
+- [ ] Code review process updated for integration considerations
+- [ ] Pair programming approach planned for critical integration points
+- [ ] Knowledge transfer plan for existing system context
+- [ ] Documentation update process defined
+- [ ] Communication plan for development team coordination
+- [ ] Timeline buffer included for integration complexity
+
+### 5.3 Deployment Strategy Validation
+
+- [ ] Deployment approach minimizes downtime
+- [ ] Blue-green or canary deployment strategy implemented
+- [ ] Database migration strategy tested and validated
+- [ ] Configuration management updated appropriately
+- [ ] Environment-specific considerations addressed
+- [ ] Health checks updated for new components
+- [ ] Monitoring dashboards updated for new metrics
+- [ ] Incident response procedures updated
+
+## 6. STAKEHOLDER ALIGNMENT VALIDATION
+
+[[LLM: Stakeholder surprises kill brownfield projects. Validate that:
+
+1. ALL affected users have been identified (not just the obvious ones)
+2. Impact on each user group is documented and communicated
+3. Training needs are realistic (users resist change)
+4. Support team is genuinely prepared (not just informed)
+5. Business continuity isn't just assumed - it's planned
+
+Look for hidden stakeholders - that batch job that runs at 2 AM, the partner API that depends on current behavior, the report that expects specific data formats. Check cron jobs, scheduled tasks, and external integrations.]]
+
+### 6.1 User Impact Assessment
+
+- [ ] Existing user workflows analyzed for impact
+- [ ] User communication plan developed for changes
+- [ ] Training materials updated for new functionality
+- [ ] Support documentation updated comprehensively
+- [ ] User feedback collection plan implemented
+- [ ] Accessibility requirements maintained or improved
+- [ ] Performance expectations managed appropriately
+- [ ] Migration path for existing user data validated
+
+### 6.2 Team Readiness Validation
+
+- [ ] Development team familiar with existing codebase
+- [ ] QA team understands existing test coverage
+- [ ] DevOps team prepared for enhanced deployment complexity
+- [ ] Support team trained on new functionality
+- [ ] Product team aligned on success metrics
+- [ ] Stakeholders informed of timeline and scope
+- [ ] Resource allocation appropriate for enhanced complexity
+- [ ] Escalation procedures defined for integration issues
+
+### 6.3 Business Continuity Validation
+
+- [ ] Critical business processes remain uninterrupted
+- [ ] SLA requirements maintained throughout enhancement
+- [ ] Customer impact minimized and communicated
+- [ ] Revenue-generating features protected during enhancement
+- [ ] Compliance requirements maintained throughout process
+- [ ] Audit trail requirements preserved
+- [ ] Data retention policies unaffected
+- [ ] Business intelligence and reporting continuity maintained
+
+## 7. DOCUMENTATION AND COMMUNICATION VALIDATION
+
+[[LLM: In brownfield projects, documentation gaps cause integration failures. Verify that:
+
+1. Documentation accurately reflects the current state (not the ideal state)
+2. Integration points are documented with excessive detail
+3. "Tribal knowledge" has been captured in writing
+4. Change impacts are documented for every affected component
+5. Runbooks are updated for new failure modes
+
+If existing documentation is poor, this enhancement must improve it - technical debt compounds. Check actual code vs documentation for discrepancies.]]
+
+### 7.1 Documentation Standards
+
+- [ ] Enhancement documentation follows existing project standards
+- [ ] Architecture documentation updated to reflect integration
+- [ ] API documentation updated for new/changed endpoints
+- [ ] User documentation updated for new functionality
+- [ ] Developer documentation includes integration guidance
+- [ ] Deployment documentation updated for enhanced process
+- [ ] Troubleshooting guides updated for new components
+- [ ] Change log properly maintained with detailed entries
+
+### 7.2 Communication Plan Validation
+
+- [ ] Stakeholder communication plan covers all affected parties
+- [ ] Technical communication includes integration considerations
+- [ ] User communication addresses workflow changes
+- [ ] Timeline communication includes integration complexity buffers
+- [ ] Risk communication includes mitigation strategies
+- [ ] Success criteria communication aligned with measurements
+- [ ] Feedback collection mechanisms established
+- [ ] Escalation communication procedures defined
+
+### 7.3 Knowledge Transfer Planning
+
+- [ ] Existing system knowledge captured and accessible
+- [ ] New functionality knowledge transfer plan developed
+- [ ] Integration points knowledge documented comprehensively
+- [ ] Troubleshooting knowledge base updated
+- [ ] Code review knowledge shared across team
+- [ ] Deployment knowledge transferred to operations team
+- [ ] Monitoring and alerting knowledge documented
+- [ ] Historical context preserved for future enhancements
+
+## 8. SUCCESS METRICS AND MONITORING VALIDATION
+
+[[LLM: Success in brownfield isn't just about new features working - it's about everything still working. Ensure:
+
+1. Baseline metrics for existing functionality are captured
+2. Degradation thresholds are defined (when do we rollback?)
+3. New monitoring covers integration points, not just new components
+4. Success criteria include "no regression" metrics
+5. Long-term metrics capture gradual degradation
+
+Without proper baselines, you can't prove the enhancement didn't break anything. Verify specific metrics and thresholds.]]
+
+### 8.1 Success Criteria Definition
+
+- [ ] Enhancement success metrics clearly defined and measurable
+- [ ] Existing system performance baselines established
+- [ ] User satisfaction metrics include existing functionality
+- [ ] Business impact metrics account for integration complexity
+- [ ] Technical health metrics cover enhanced system
+- [ ] Quality metrics include regression prevention
+- [ ] Timeline success criteria realistic for brownfield complexity
+- [ ] Resource utilization metrics appropriate for enhanced system
+
+### 8.2 Monitoring Strategy Validation
+
+- [ ] Existing monitoring capabilities preserved and enhanced
+- [ ] New component monitoring integrated with existing dashboards
+- [ ] Alert thresholds updated for enhanced system complexity
+- [ ] Log aggregation includes new components appropriately
+- [ ] Performance monitoring covers integration points
+- [ ] Security monitoring enhanced for new attack surfaces
+- [ ] User experience monitoring includes existing workflows
+- [ ] Business metrics monitoring updated for enhanced functionality
+
+### 8.3 Feedback and Iteration Planning
+
+- [ ] User feedback collection includes existing functionality assessment
+- [ ] Technical feedback loops established for integration health
+- [ ] Performance feedback includes existing system impact
+- [ ] Business feedback loops capture integration value
+- [ ] Iteration planning includes integration refinement
+- [ ] Continuous improvement process updated for enhanced complexity
+- [ ] Learning capture process includes integration lessons
+- [ ] Future enhancement planning considers established integration patterns
+
+---
+
+## CHECKLIST COMPLETION VALIDATION
+
+### Final Validation Steps
+
+- [ ] All sections completed with evidence and documentation
+- [ ] Critical risks identified and mitigation strategies implemented
+- [ ] Stakeholder sign-off obtained for high-risk integration decisions
+- [ ] Go/no-go decision criteria established with clear thresholds
+- [ ] Rollback triggers and procedures tested and validated
+- [ ] Success metrics baseline established and monitoring confirmed
+- [ ] Team readiness confirmed through final review and sign-off
+- [ ] Communication plan activated and stakeholders informed
+
+### Documentation Artifacts
+
+- [ ] Completed brownfield PRD with validated existing system analysis
+- [ ] Completed brownfield architecture with integration specifications
+- [ ] Risk assessment document with mitigation strategies
+- [ ] Integration testing plan with existing system coverage
+- [ ] Deployment plan with rollback procedures
+- [ ] Monitoring and alerting configuration updates
+- [ ] Team readiness assessment with training completion
+- [ ] Stakeholder communication plan with timeline and milestones
+
+---
+
+**Checklist Completion Date:** **\*\***\_\_\_**\*\***  
+**Product Owner Signature:** **\*\***\_\_\_**\*\***  
+**Technical Lead Approval:** **\*\***\_\_\_**\*\***  
+**Stakeholder Sign-off:** **\*\***\_\_\_**\*\***
+
+[[LLM: FINAL BROWNFIELD VALIDATION REPORT GENERATION
+
+Generate a comprehensive brownfield validation report with special attention to integration risks:
+
+1. Executive Summary
+
+   - Enhancement readiness: GO / NO-GO / CONDITIONAL
+   - Critical integration risks identified
+   - Estimated risk to existing functionality (High/Medium/Low)
+   - Confidence level in success (percentage with justification)
+
+2. Integration Risk Analysis
+
+   - Top 5 integration risks by severity
+   - Specific code/components at risk
+   - User impact if risks materialize
+   - Mitigation effectiveness assessment
+
+3. Existing System Impact
+
+   - Features/workflows that could be affected
+   - Performance impact predictions
+   - Security posture changes
+   - Technical debt introduced vs. resolved
+
+4. Go/No-Go Recommendation
+
+   - Must-fix items before proceeding
+   - Acceptable risks with mitigation
+   - Success probability assessment
+   - Alternative approaches if No-Go
+
+5. Rollback Readiness
+
+   - Rollback procedure completeness
+   - Time to rollback estimate
+   - Data recovery considerations
+   - User communication plan
+
+6. 30-60-90 Day Outlook
+   - Expected issues in first 30 days
+   - Monitoring focus areas
+   - Success validation milestones
+   - Long-term integration health indicators
+
+After presenting this report, offer to deep-dive into any section, especially high-risk areas or failed validations. Ask if the user wants specific recommendations for reducing integration risks.]]