@cloudkinetix/bmad-enhanced

# Universal Three-Way Sync Analysis Utilities Core utilities for analyzing and maintaining synchronization between git commits, BMAD documentation, and JIRA issues across all JIRA agent commands and reports. ## Core Philosophy Every report and command should provide visibility into the alignment health of git (actual development), BMAD (planned work), and JIRA (tracked execution). This universal sync analysis prevents organizational drift and ensures authentic agile process insights. ## Sync Health Calculation Framework ### Three-Way Sync Metrics **Git ↔ JIRA Sync Health:** ``` Aligned Percentage = (Aligned Issues / Total Active Issues) × 100 - Aligned: Issues with corresponding git activity in appropriate timeframe - Status Lag: Issues behind actual development progress - Phantom Progress: Issues marked "Done" without supporting commits - Missing Issues: Significant git work without JIRA tracking ``` **Git ↔ BMAD Sync Health:** ``` Documentation Alignment = (Correlated Commits / Total Commits) × 100 - Documented: Commits that correlate with BMAD stories - Documentation Drift: Stories needing updates from commits - Scope Creep: Commits extending beyond story acceptance criteria - Emergent Work: Commits without BMAD story coverage ``` **JIRA ↔ BMAD Sync Health:** ``` Planning Alignment = (Consistent Items / Total Items) × 100 - Progress Aligned: Issues matching story progress indicators - Priority Conflicts: Mismatched priorities between systems - Requirement Drift: Acceptance criteria divergence - Link Validation: Proper cross-references between systems ``` ### Sync Status Indicators **Standard Status Icons:** - ✅ **Aligned**: Systems in sync, no action needed - ⚠️ **Minor Drift**: Attention needed, low risk - 🚨 **Major Misalignment**: Action required, medium risk - 📋 **Missing Data**: Information gap, needs investigation - 🔄 **Sync in Progress**: Alignment action underway - ❌ **Critical Failure**: Severe misalignment, high risk **Health Score Thresholds:** - **90-100%**: Excellent (✅) - **80-89%**: Good (✅) - **70-79%**: Attention Needed (⚠️) - **60-69%**: Action Required (🚨) - **50-59%**: Poor Alignment (🚨) - **Below 50%**: Critical (❌) ## Git Analysis Functions ### Commit Analysis Utilities **Basic Git Data Extraction:** ```bash # Yesterday's activity analysis git log --since="yesterday" --oneline --stat --all --no-merges # File change impact analysis git diff --name-status HEAD~1 HEAD # Branch activity patterns git log --graph --oneline --since="yesterday" --all # Developer-specific analysis git log --since="yesterday" --author="email" --oneline --stat # Code review and collaboration git log --since="yesterday" --grep="review\|merge\|fix\|feat" ``` **Advanced Pattern Recognition:** - **Story Reference Detection**: Extract BMAD story references from commit messages - **Component Mapping**: Map file paths to BMAD story components - **Work Type Classification**: Development, testing, refactoring, documentation - **Quality Indicators**: Test additions, bug fixes, performance improvements - **Collaboration Patterns**: Pair programming, code review participation ### Git-to-System Correlation **BMAD Story Correlation:** ``` Correlation Confidence Scoring: - Direct Reference: 95% (story filename in commit message) - Component Match: 85% (modified files match story components) - Keyword Match: 70% (commit keywords match story acceptance criteria) - Temporal Match: 60% (commit timing aligns with story work period) - File Path Match: 50% (modified paths related to story area) ``` **JIRA Issue Correlation:** ``` Correlation Strategies: - Issue Key Reference: Look for PROJ-123 patterns in commits - Branch Name Analysis: Extract issue keys from feature branch names - Temporal Proximity: Match commit timing with JIRA activity - Developer Assignment: Correlate commit author with JIRA assignee - Component Mapping: Map git changes to JIRA component fields ``` ## BMAD Documentation Analysis ### Story Status Assessment **Story Progress Indicators:** - **Planning Phase**: Story exists, no development activity - **In Development**: Active commits correlating with story - **Implementation Complete**: Code changes cover acceptance criteria - **Documentation Drift**: Implementation diverged from story - **Scope Expansion**: Development exceeded story boundaries **Story-Commit Mapping Intelligence:** ``` File Path Analysis: - Extract component paths from story documentation - Match git file changes to story component structure - Identify new components not covered in stories - Flag architectural changes affecting multiple stories ``` **Acceptance Criteria Tracking:** ``` Progress Mapping: - Parse acceptance criteria from BMAD stories - Map git commits to specific criteria completion - Estimate completion percentage based on file changes - Identify criteria requiring story updates ``` ### Documentation Health Metrics **Story Accuracy Assessment:** - **Current**: Story reflects actual implementation - **Minor Drift**: Small divergence, easy to reconcile - **Major Drift**: Significant changes needed - **Outdated**: Story no longer matches implementation - **Scope Creep**: Implementation exceeded planned scope ## JIRA Integration Analysis ### Issue Status Correlation **Development Activity Validation:** ``` Issue Status vs Git Activity: - "To Do" → No recent commits (✅ Expected) - "In Progress" → Active commits (✅ Aligned) - "In Progress" → No commits for 3+ days (⚠️ Stalled) - "Done" → Recent commits (✅ Completed) - "Done" → No supporting commits (🚨 Phantom) ``` **Effort Tracking Correlation:** ``` Time Logging vs Commit Activity: - High commit activity vs low time logs (⚠️ Under-reporting) - High time logs vs low commit activity (⚠️ Over-reporting) - Consistent patterns between commits and time (✅ Accurate) ``` ### JIRA-BMAD Consistency **Priority Alignment:** ``` Strategic vs Tactical Priority: - BMAD strategic importance vs JIRA priority - Epic hierarchy consistency across systems - Resource allocation alignment - Stakeholder expectation management ``` **Requirements Traceability:** ``` Acceptance Criteria Sync: - JIRA criteria match BMAD story definitions - Implementation coverage of all criteria - Stakeholder approval alignment - Change management tracking ``` ## Universal Sync Dashboard Generation ### Standard Dashboard Components **Sync Health Summary:** ```markdown ## 📊 System Alignment Health **Three-Way Sync Status:** - **Git ↔ JIRA**: {{git_jira_percentage}}% ({{git_jira_status_icon}}) - **Git ↔ BMAD**: {{git_bmad_percentage}}% ({{git_bmad_status_icon}}) - **JIRA ↔ BMAD**: {{jira_bmad_percentage}}% ({{jira_bmad_status_icon}}) **Overall Health**: {{overall_health_percentage}}% ({{overall_status_icon}}) ``` **Detailed Sync Breakdown:** ```markdown ### Git ↔ JIRA Alignment - ✅ **Aligned Issues**: {{aligned_count}} issues match git activity - ⚠️ **Status Lag**: {{lag_count}} issues behind development progress - 🚨 **Phantom Progress**: {{phantom_count}} issues done without commits - 📋 **Missing Issues**: {{missing_count}} git work without JIRA tracking ### Git ↔ BMAD Alignment - ✅ **Documented Work**: {{documented_count}} commits correlate with stories - ⚠️ **Documentation Drift**: {{drift_count}} stories need updates - 🚨 **Scope Creep**: {{creep_count}} commits exceed story scope - 📋 **Emergent Work**: {{emergent_count}} commits without story coverage ### JIRA ↔ BMAD Alignment - ✅ **Progress Aligned**: {{aligned_count}} consistent progress indicators - ⚠️ **Priority Conflicts**: {{conflict_count}} priority mismatches - 🚨 **Requirement Drift**: {{drift_count}} acceptance criteria divergence - 📋 **Link Validation**: {{broken_count}} broken cross-references ``` ### Context-Aware Sync Analysis **Command-Specific Sync Focus:** **For Story Operations (\*sync, story-related):** ```markdown ### Story-Specific Sync Health **{{story_filename}}**: - **Git Activity**: {{commit_count}} commits, {{confidence}}% correlation - **JIRA Tracking**: {{issue_key}} ({{status}}) - {{sync_status}} - **Progress**: {{completion_percentage}}% based on acceptance criteria - **Sync Actions**: {{required_actions}} ``` **For Sprint Operations (*standup, *report):** ```markdown ### Sprint-Wide Sync Health **Sprint {{sprint_name}}**: - **Active Stories**: {{total_stories}} ({{synced_stories}} synced) - **Development Velocity**: {{commits_per_day}} commits/day vs {{planned_velocity}} - **JIRA Currency**: {{current_issues}}/{{total_issues}} issues current - **Critical Gaps**: {{critical_count}} requiring immediate attention ``` **For Strategic Operations (*roadmap, *reconcile):** ```markdown ### Strategic Alignment Health **Portfolio View**: - **Planning Accuracy**: {{accuracy_percentage}}% over last {{timeframe}} - **Execution Variance**: {{variance_percentage}}% timeline drift - **Resource Alignment**: {{resource_percentage}}% allocation accuracy - **Stakeholder Sync**: {{stakeholder_percentage}}% expectation alignment ``` ## Performance Optimization ### Caching Strategy **Git Analysis Caching:** - Cache commit analysis for 24 hours - Incremental updates for new commits - Background refresh for active repositories - Smart invalidation on branch changes **Correlation Result Caching:** - Store story-commit mappings - Cache JIRA-git correlations - Persist confidence scores - Update on system changes ### Scalability Considerations **Large Repository Handling:** - Limit git analysis to recent timeframes - Focus on active branches and developers - Use git log filtering for performance - Implement incremental analysis **Team Size Optimization:** - Scale analysis depth with team size - Optimize correlation algorithms - Batch process sync health calculations - Provide summary vs detailed modes ## Sync Action Generation ### Automatic Action Recommendations **High Priority Actions (Execute Today):** ```markdown 1. **Update JIRA Status**: Move {{issue_key}} to "{{recommended_status}}" based on {{commit_count}} commits 2. **Refresh Story**: Update {{story_file}} with implementation changes ({{confidence}}% drift detected) 3. **Log Time**: Add {{estimated_hours}} hours to {{issue_key}} based on commit activity ``` **Medium Priority Actions (This Week):** ```markdown - **Documentation Review**: {{story_count}} stories showing drift - **Priority Alignment**: {{conflict_count}} JIRA priorities need BMAD review - **Link Validation**: {{broken_count}} cross-references need repair ``` **Automated Sync Suggestions:** ```bash # Suggested JIRA API calls mcp__mcp-atlassian__jira_transition_issue({{issue_key}}, {{transition_id}}) mcp__mcp-atlassian__jira_update_issue({{issue_key}}, {status: "{{new_status}}"}) mcp__mcp-atlassian__jira_add_worklog({{issue_key}}, "{{estimated_time}}") ``` ## Error Handling and Fallbacks ### Git Repository Issues **Repository Access Problems:** - Graceful degradation when git is unavailable - Clear messaging about reduced functionality - Alternative analysis using available data - Suggestion for git setup improvements **Large Repository Performance:** - Automatic timeframe limiting - Progressive analysis with user consent - Performance warnings and alternatives - Caching to improve subsequent runs ### JIRA Connectivity Issues **MCP Tool Failures:** - Fall back to BMAD-Git sync only - Clear indication of reduced sync analysis - Cached JIRA data utilization - Guidance for MCP tool setup ### BMAD Documentation Issues **Missing or Malformed Stories:** - Skip malformed stories with warnings - Provide sync analysis for available stories - Suggest documentation improvements - Continue with git-JIRA correlation ## Configuration and Customization ### Sync Depth Configuration **Analysis Depth Levels:** ```yaml sync_analysis: depth: "detailed" # summary | detailed | alert | context timeframe: "7d" # Analysis window for git commits cache_duration: "24h" # How long to cache results correlation_threshold: 70 # Minimum confidence for correlations performance_mode: "auto" # auto | fast | thorough ``` **Team-Specific Thresholds:** ```yaml team_config: health_thresholds: excellent: 90 good: 80 attention: 70 action_required: 60 poor: 50 correlation_patterns: story_reference_regex: "\\b[A-Z]+-\\d+\\b" component_mapping: "auto" # auto | manual | disabled ``` ### Customizable Indicators **Team Workflow Adaptation:** - Customize status icon meanings - Adjust health score thresholds - Configure correlation confidence levels - Adapt to team commit patterns **Report Integration Options:** - Choose sync depth per command - Configure automatic vs manual refresh - Set alert thresholds for critical gaps - Customize action recommendation priorities This universal sync analysis framework ensures every JIRA agent command provides visibility into organizational alignment, preventing drift and enabling data-driven agile process improvements.