# 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