@cloudkinetix/bmad-enhanced

# Task: Generate Semantic Analysis Report > 🧠 **LLM-Native Analysis Documentation** - Creates comprehensive semantic dependency analysis reports with user review capabilities ## Description Generates detailed reports from LLM-native semantic analysis, documenting discovered dependencies, hidden conflicts, architectural impacts, and providing interactive sections for user review and enhancement. ## Purpose - **Transparency**: Show AI reasoning behind dependency detection - **User Review**: Enable critiques and corrections - **Learning**: Capture feedback for improvement - **Documentation**: Create audit trail of analysis decisions - **Confidence Building**: Show certainty levels and alternatives ## Process Flow ### Step 1: Invoke LLM Dependency Analysis ```yaml [[LLM: Perform deep semantic analysis of work items]] ANALYSIS_REQUEST: work_items: [List of work descriptions] analysis_depth: deep dimensions: - file_modifications - api_contract_changes - data_model_impacts - business_logic_conflicts - architectural_patterns - test_dependencies - performance_implications OUTPUT: - Direct dependencies with confidence - Semantic dependencies with reasoning - Hidden dependencies with discovery method - Risk assessments with mitigation - Wave planning recommendations ``` ### Step 2: Structure Analysis Results ```yaml [[LLM: Organize analysis into reportable structure]] DEPENDENCY_MATRIX: for_each_work_item: - predicted_files: [with confidence %] - api_impacts: [endpoints affected] - semantic_deps: [business logic connections] - hidden_risks: [non-obvious impacts] - architectural_concerns: [pattern violations] CONFIDENCE_METRICS: - overall: percentage - by_category: file_deps: percentage semantic_deps: percentage hidden_deps: percentage wave_planning: percentage LOW_CONFIDENCE_AREAS: - List areas needing human validation - Explain why confidence is low - Suggest what info would help ``` ### Step 3: Generate Main Analysis Report ```yaml [[LLM: Create comprehensive semantic-analysis.md]] REPORT_SECTIONS: 1. Executive Summary - Total dependencies found - Hidden dependencies count - Overall risk assessment - Confidence level 2. Dependency Analysis Matrix - Visual table of all dependencies - Color coding by risk level - Confidence indicators 3. Hidden Dependencies Deep Dive - Each with full explanation - Discovery reasoning - Impact if missed - Mitigation strategies 4. Architectural Impact Assessment - Service boundary analysis - Design pattern implications - Performance considerations - Security implications 5. Wave Planning Rationale - Why waves composed this way - Alternative compositions - Risk/benefit tradeoffs 6. Confidence Breakdown - Per-category confidence - Factors affecting confidence - Areas needing validation SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/semantic-analysis.md ``` ### Step 4: Generate Interactive Review Document ```yaml [[LLM: Create user-review.md for feedback]] REVIEW_SECTIONS: 1. Quick Agreement Scale - Checkboxes for agreement levels - Space for quick notes 2. Dependency Review - AI's analysis per work item - Structured feedback areas - Correction templates 3. Wave Planning Review - Current plan visualization - Alternative suggestion area - Reasoning space 4. Additional Context - Architecture notes section - Business logic clarifications - Historical context 5. AI Improvement Feedback - What was accurate - What was missed - Suggestions for better analysis INTERACTIVE_ELEMENTS: - YAML templates for corrections - Checkboxes for agreement - Free text areas for insights - Structured feedback forms SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/user-review.md ``` ### Step 5: Generate Dependency Visualization ```yaml [[LLM: Create visual representations]] DEPENDENCY_GRAPH: format: mermaid elements: - Work items as nodes - Dependencies as edges - Risk levels as colors - Hidden deps as dashed lines WAVE_TIMELINE: format: ascii_art show: - Wave sequences - Parallel items - Duration estimates - Dependencies resolved RISK_HEATMAP: format: table dimensions: - Work items vs work items - Color by conflict probability - Include confidence levels SAVE_VISUALS: - dependency-graph.md (mermaid) - wave-timeline.txt (ascii) - risk-heatmap.md (table) ``` ### Step 6: Create Machine-Readable Outputs ```yaml [[LLM: Generate structured data files]] DEPENDENCY_MATRIX_JSON: schema: version: "1.0" work_items: array dependencies: direct: array semantic: array hidden: array architectural: array risks: object confidence: object wave_plan: object SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/dependency-matrix.json LEARNING_LOG_JSON: schema: analysis_id: string timestamp: iso8601 confidence_levels: object low_confidence_areas: array questions_for_user: array patterns_detected: array SAVE_AS: .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/learning-log.json ``` ### Step 7: Integration with Pre-Execution Report ```yaml [[LLM: Enhance pre-execution report with semantic analysis]] ADD_TO_PRE_EXECUTION_REPORT: new_section: "🧠 Semantic Dependency Analysis" subsections: - Key findings summary - Hidden dependencies alert - Confidence indicators - Link to full analysis example: """ ## 🧠 Semantic Dependency Analysis **Analysis Depth**: Deep semantic scan **Hidden Dependencies Found**: 3 **Overall Confidence**: 85% ### Key Findings - Auth changes affect 3 downstream services - Hidden coupling between logging and metrics - API contract change impacts mobile app [View Full Analysis](./semantic-analysis.md) [Provide Feedback](./user-review.md) """ ``` ## Output Structure ``` .bmad-workspace/ck-parallel-dev/runs/{{run-id}}/ ├── semantic-analysis.md # Main analysis report ├── user-review.md # Interactive review doc ├── dependency-matrix.json # Machine-readable data ├── dependency-graph.md # Visual graph (mermaid) ├── wave-timeline.txt # ASCII timeline ├── risk-heatmap.md # Risk visualization ├── learning-log.json # For AI improvement └── pre-execution-report.md # Enhanced with analysis ``` ## Integration Points ### With LLM Dependency Analyzer - Receives full analysis results - Requests additional analysis if needed - Handles confidence metrics ### With Pre-Execution Report - Adds semantic analysis section - Links to detailed reports - Shows confidence levels ### With User Feedback Loop - Generates review documents - Collects structured feedback - Updates learning logs ## Example Usage ```bash # During parallel-dev execution Performing semantic dependency analysis... ✅ Analysis complete (85% confidence) ✅ Found 12 dependencies (3 hidden) ✅ Generated 6 report files 📊 Semantic Analysis Reports: - Full Analysis: .bmad-workspace/ck-parallel-dev/runs/20250704-093000-xyz/semantic-analysis.md - Review Doc: .bmad-workspace/ck-parallel-dev/runs/20250704-093000-xyz/user-review.md - Visualizations: dependency-graph.md, wave-timeline.txt Review the analysis above. Would you like to: 1. Review and provide feedback 2. Proceed with current analysis 3. Regenerate with different parameters Choice: ``` ## Best Practices 1. **Always Generate**: Even for simple cases 2. **Show Confidence**: Be transparent about uncertainty 3. **Enable Review**: Make feedback easy 4. **Learn Continuously**: Use feedback to improve 5. **Visualize Complexity**: Use graphs for clarity ## Success Metrics - User reviews > 50% of analyses - Feedback improves accuracy > 10% - Hidden dependencies caught > 90% - User confidence in analysis > 80% - Report generation < 30 seconds