@cloudkinetix/bmad-enhanced

--- name: Semantic Analysis Reporter version: 1.0.0 role: Generate comprehensive semantic analysis reports for parallel development description: Creates detailed reports of LLM-native dependency analysis with user review capabilities capabilities: - Semantic dependency visualization - Hidden conflict documentation - Architectural impact reporting - User review integration - Learning from corrections --- # Semantic Analysis Reporter ## Purpose Generates comprehensive, reviewable reports from LLM-native semantic analysis, enabling users to understand, critique, and enhance the AI's dependency analysis and wave planning decisions. ## Core Features ### 1. Multi-Format Report Generation - **Markdown Reports**: Human-readable analysis with visual elements - **JSON Data**: Machine-readable dependency matrices - **Interactive Sections**: Areas for user review and feedback - **Visual Diagrams**: Dependency graphs and wave visualizations ### 2. Analysis Documentation - **Reasoning Transparency**: Why dependencies were identified - **Confidence Levels**: How certain the analysis is - **Alternative Interpretations**: Other possible dependency patterns - **Learning Opportunities**: Areas where user input would help ## Report Generation Process ### Step 1: Gather Analysis Results ```javascript async function gatherAnalysisData(workItems, analysisResults) { return { timestamp: new Date().toISOString(), workItems: workItems, dependencies: { direct: analysisResults.directDependencies, semantic: analysisResults.semanticDependencies, hidden: analysisResults.hiddenDependencies, architectural: analysisResults.architecturalDependencies, }, risks: analysisResults.riskAssessment, wavePlan: analysisResults.executionPlan, confidence: analysisResults.confidenceMetrics, }; } ``` ### Step 2: Generate Semantic Analysis Report ```markdown # Semantic Dependency Analysis Report **Generated**: {{timestamp}} **Analysis ID**: {{analysisId}} **Confidence Level**: {{overall_confidence}}% ## Executive Summary The LLM-native analysis identified {{total_dependencies}} dependencies across {{work_item_count}} work items, including {{hidden_count}} hidden dependencies that would not be detected by traditional file-based analysis. ### Key Findings - **Direct File Conflicts**: {{direct_conflicts}} - **Semantic Dependencies**: {{semantic_deps}} - **Architectural Impacts**: {{arch_impacts}} - **Risk Level**: {{risk_level}} ({{risk_reason}}) ## Detailed Dependency Analysis ### Work Item Dependencies Matrix | Work Item | Direct Files | Semantic Dependencies | Hidden Risks | Wave | | --------- | ------------ | --------------------- | ------------ | ---- | {{#each workItems}} | {{name}} | {{files}} | {{semanticDeps}} | {{risks}} | {{wave}} | {{/each}} ### Hidden Dependencies Discovered {{#each hiddenDependencies}} #### {{index}}. {{title}} **Type**: {{type}} **Affected Components**: {{components}} **Discovery Method**: {{method}} **Confidence**: {{confidence}}% **Analysis**: {{reasoning}} **Impact if Missed**: {{impact}} **Mitigation Strategy**: {{mitigation}} --- {{/each}} ### API Contract Dependencies {{#each apiDependencies}} #### {{endpoint}} **Consumers**: {{consumers}} **Contract Changes**: {{changes}} **Breaking Change Risk**: {{breaking_risk}} {{/each}} ## Architectural Impact Assessment ### Service Boundaries {{architecturalAnalysis}} ### Design Pattern Implications {{patternAnalysis}} ### Performance Considerations {{performanceImpact}} ## Wave Planning Rationale ### Recommended Execution Waves ``` {{waveVisualization}} ```` ### Wave Composition Reasoning {{#each waves}} #### Wave {{number}}: {{title}} **Work Items**: {{items}} **Rationale**: {{reasoning}} **Dependencies Resolved**: {{resolved}} **Risk Level**: {{risk}} {{/each}} ## User Review Section ### Dependency Analysis for Review > 📝 **Instructions**: Please review the analysis below and add your corrections or insights in the marked sections. {{#each workItems}} #### Work Item: {{description}} **AI Analysis**: - Files to modify: {{predictedFiles}} - API impacts: {{apiImpacts}} - Hidden dependencies: {{hiddenDeps}} - Architectural concerns: {{archConcerns}} **Your Review**: ```yaml # Please provide your feedback here corrections: files: # Add any files the AI missed dependencies: # Identify any missed dependencies risks: # Note any additional risks agreement_level: # high/medium/low notes: | # Additional insights or corrections ```` --- {{/each}} ### Wave Planning Review **AI's Proposed Wave Plan**: {{proposedWavePlan}} **Your Alternative Suggestion**: ```yaml # Propose alternative wave composition if needed alternative_waves: wave_1: items: [] reasoning: "" wave_2: items: [] reasoning: "" ``` ## Confidence Metrics ### Analysis Confidence Breakdown | Aspect | Confidence | Factors | | --------------------- | ------------------------ | -------------------- | | File Dependencies | {{file_confidence}}% | {{file_factors}} | | Semantic Dependencies | {{semantic_confidence}}% | {{semantic_factors}} | | Hidden Dependencies | {{hidden_confidence}}% | {{hidden_factors}} | | Wave Planning | {{wave_confidence}}% | {{wave_factors}} | ### Areas Needing Human Validation {{#each lowConfidenceAreas}} - **{{area}}**: {{reason}} (Confidence: {{confidence}}%) {{/each}} ## Learning Opportunities ### Questions for User {{#each questions}} {{index}}. {{question}} - Context: {{context}} - Why this helps: {{benefit}} {{/each}} ### Pattern Recognition Based on this analysis, the AI identified these patterns that could improve future analyses: {{#each patterns}} - **Pattern**: {{pattern}} - **Occurrence**: {{occurrence}} - **Implication**: {{implication}} {{/each}} ```` ### Step 3: Generate Interactive Review File ```markdown # Semantic Analysis Review Document **Instructions**: This document is for your review and enhancement of the AI analysis. Your feedback will improve future analyses. ## Quick Agreement Scale For each section below, indicate your agreement level: - ✅ **Agree** - Analysis is accurate - ⚠️ **Partially Agree** - Some corrections needed - ❌ **Disagree** - Significant issues with analysis ## Dependency Analysis Review ### 1. File Dependencies **AI's Analysis**: [List of files] **Your Agreement**: [ ] Agree [ ] Partial [ ] Disagree **Corrections**: ```` Add your corrections here... ``` ### 2. Hidden Dependencies **AI Found**: [List of hidden dependencies] **Missed Dependencies**: ``` List any dependencies the AI missed... ``` ### 3. Risk Assessment **AI's Risk Level**: {{risk_level}} **Your Assessment**: [ ] Too High [ ] Accurate [ ] Too Low **Reasoning**: ``` Explain your risk assessment... ``` ## Enhanced Wave Planning ### Current Plan Issues ``` Describe any issues with the proposed wave plan... ```` ### Improved Wave Composition ```yaml wave_1: items: [] reasoning: "" wave_2: items: [] reasoning: "" ```` ## Additional Context ### Architecture Notes ``` Provide any architectural context the AI should know... ``` ### Business Logic Clarifications ``` Clarify any business rules or logic... ``` ### Historical Context ``` Note any past issues or patterns relevant to this work... ``` ## Feedback for AI Improvement ### What the AI Got Right ``` Highlight accurate insights... ``` ### What the AI Missed ``` Note important missed aspects... ``` ### Suggestions for Better Analysis ``` How could the AI improve its analysis approach... ``` ```` ### Step 4: Generate Learning Log ```json { "analysisId": "{{analysisId}}", "timestamp": "{{timestamp}}", "userFeedback": { "agreementLevels": { "fileDependencies": "high|medium|low", "semanticDependencies": "high|medium|low", "hiddenDependencies": "high|medium|low", "wavePlanning": "high|medium|low" }, "corrections": { "missedFiles": [], "missedDependencies": [], "incorrectRisks": [], "betterWaves": {} }, "insights": { "architecturalContext": "", "businessLogic": "", "historicalPatterns": "" } }, "learningPoints": [ { "type": "pattern", "description": "User consistently identifies X type of dependency", "action": "Increase weight for X in future analyses" } ] } ```` ## Integration with Report Generation ### Update Report Flow ```javascript async function generateEnhancedReports(analysisResults, runId) { const reportsDir = `.bmad-workspace/ck-parallel-dev/runs/${runId}`; // 1. Generate semantic analysis report const semanticReport = await generateSemanticAnalysisReport(analysisResults); await saveReport(`${reportsDir}/semantic-analysis.md`, semanticReport); // 2. Generate review document const reviewDoc = await generateReviewDocument(analysisResults); await saveReport(`${reportsDir}/user-review.md`, reviewDoc); // 3. Generate dependency matrix const matrix = await generateDependencyMatrix(analysisResults); await saveJson(`${reportsDir}/dependency-matrix.json`, matrix); // 4. Update pre-execution report const preExecReport = await enhancePreExecutionReport(analysisResults); await saveReport(`${reportsDir}/pre-execution-report.md`, preExecReport); // 5. Create learning log const learningLog = createLearningLog(analysisResults); await saveJson(`${reportsDir}/learning-log.json`, learningLog); return { reports: [ "semantic-analysis.md", "user-review.md", "dependency-matrix.json", "pre-execution-report.md", ], reviewRequired: true, }; } ``` ## Visual Elements ### Dependency Graph Generation ```mermaid graph TD A[Auth Service] -->|API Contract| B[User Profile] A -->|Session Data| C[Session Manager] B -->|User Model| D[Admin Dashboard] C -->|Token Validation| A style A fill:#f9f,stroke:#333,stroke-width:4px style B fill:#bbf,stroke:#333,stroke-width:2px ``` ### Wave Timeline Visualization ``` Wave 1 (0-2h): ████████████ Auth, Logging Wave 2 (2-3h): ░░░░░░░░████ Profile Wave 3 (3-4h): ░░░░░░░░░░░░████ Admin ``` ## Report Output Structure ``` .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/ ├── semantic-analysis.md # Complete semantic analysis ├── user-review.md # Interactive review document ├── dependency-matrix.json # Machine-readable dependencies ├── dependency-graph.svg # Visual dependency graph ├── wave-timeline.png # Wave execution timeline ├── learning-log.json # Feedback for improvement └── enhanced-report.md # All-in-one enhanced report ``` ## Usage Example ```javascript // Generate comprehensive semantic analysis reports const reporter = new SemanticAnalysisReporter(); // Perform analysis const analysis = await llmAnalyzer.analyzeDependencies(workItems); // Generate reports const reports = await reporter.generateReports(analysis, runId); // Show to user console.log(` 📊 Semantic Analysis Complete Reports generated in: ${reports.directory} - Semantic Analysis: ${reports.semantic} - User Review Doc: ${reports.review} - Dependency Matrix: ${reports.matrix} Please review the analysis and provide feedback in user-review.md `); // After user review const feedback = await reporter.collectUserFeedback(runId); await reporter.updateLearningLog(feedback); // Regenerate with improvements const improvedAnalysis = await llmAnalyzer.reanalyze(workItems, feedback); ``` ## Benefits 1. **Transparency**: Users understand AI reasoning 2. **Correctability**: Users can fix AI mistakes 3. **Learning**: System improves from feedback 4. **Confidence**: Users trust the analysis more 5. **Documentation**: Complete audit trail This reporter transforms opaque AI analysis into transparent, reviewable, and improvable intelligence for parallel development planning.