# report

Intelligent reporting hub that generates any type of report you need - from sprint health to roadmaps, team metrics to three-way correlation analysis.

[[LLM: CRITICAL REQUIREMENT - ALL reports MUST be saved to files!
This is a report generation task, not a display task.
EVERY report generated MUST be:

1. Written to a markdown file in the appropriate directory
2. Saved using the Write tool
3. Confirmed with a success message showing the full file path
   DO NOT just display reports in the chat - they MUST be persisted to files!
   ]]

## MCP Tool Requirements

[[LLM: MANDATORY - Before generating any report:

1. PROJECT MAPPING VALIDATION:
   - Check if `.bmad-workspace/ck-jira-integration/config/jira-expansion-config.yaml` exists
   - If NOT exists, check legacy `.bmad-workspace/config/jira-expansion-config.yaml`
   - If NOT exists:
     - ERROR: "❌ JIRA expansion config not configured. Please run 'setup' first."
     - Guide user to run setup task
     - DO NOT proceed with report generation
   - If exists:
     - Load and display configuration at report start:
     ```
     📋 Report Configuration:
     JIRA Project: {{project_key}} - {{project_name}}
     Git Repositories:
       - Primary: {{primary_path}}
       {{#each additional_repos}}
       - {{name}}: {{path}}
       {{/each}}
     ```

2. TIME ACCURACY VERIFICATION:
   - Check if `mcp__MCP_DOCKER__get_current_time` is available
   - If available: Use with timezone "America/Los_Angeles" for all timestamps
   - If NOT available:
     - Add prominent warning at report top: "⚠️ TIME ACCURACY WARNING: Real-time data unavailable"
     - Mark all timestamps with ⚠️ symbol
   - Always show report generation time in header

3. DATA SOURCE VERIFICATION:
   - Check for Atlassian MCP tools (prefix 'mcp**mcp-atlassian**')
   - Check for BMAD documentation in docs/
   - Check for git repository access
   - Adapt report based on available data sources
   - Use ALL configured git repositories from jira-expansion-config.yaml
     ]]

## Core Philosophy

One report command that intelligently generates the insights you need. The LLM should:

1. **Auto-detect report type** from natural language
2. **Choose optimal data sources** based on availability
3. **Scale detail level** to match audience
4. **Focus on actionable insights** not just data
5. **Include visual-ready data** for charts
6. **Provide recommendations** based on patterns

## Natural Language Triggers

### Universal Reporting

- "report"
- "generate report"
- "show report"
- "create report"
- "analytics"

### Sprint Reports

- "sprint health"
- "sprint report"
- "burndown"
- "velocity"
- "sprint metrics"

### Roadmap Reports

- "roadmap"
- "timeline"
- "release plan"
- "planning report"
- "feature timeline"

### Team Analytics

- "team performance"
- "team metrics"
- "productivity report"
- "workload analysis"
- "capacity report"

### Quality Reports

- "quality metrics"
- "bug report"
- "defect analysis"
- "test coverage"
- "quality trends"

### Correlation Reports

- "correlation report"
- "three-way sync"
- "alignment report"
- "traceability"
- "sync health"

## Intelligent Report Detection

[[LLM: Automatically determine report type:

1. Parse Request Keywords:
   - Sprint/velocity → Sprint health report
   - Roadmap/timeline → Roadmap report
   - Team/performance → Team analytics
   - Bug/quality → Quality report
   - Correlation/sync → Alignment report

2. Consider Context:
   - Current sprint phase
   - Recent team questions
   - Time of request
   - Previous reports

3. Detect Audience:
   - Executive → High-level summary
   - Team → Detailed metrics
   - Technical → Deep analytics
     ]]

## Sprint Health Reports

[[LLM: Log: report_initiated event with type='sprint_health']]

[[LLM: MANDATORY - This report MUST be written to a file:

1. Generate the complete report content
2. Create directory: `mkdir -p .bmad-workspace/ck-jira-integration/reports/sprint/`
3. Use Write tool to save to: `.bmad-workspace/ck-jira-integration/reports/sprint/sprint-health-{{sprint_name}}-YYYY-MM-DD.md`
4. Confirm file was written: "✅ Sprint health report saved to: {{full_path}}"
   DO NOT just display the report - it MUST be saved to a file!
   ]]

### Data Collection

- [[LLM: Use `mcp__mcp-atlassian__jira_search` with JQL: "sprint in openSprints()"]]
- Calculate burndown/burnup
- Track velocity trends
- Monitor scope changes
- Assess sprint goals

[[LLM: Track: metrics calculated and data completeness]]

### Key Metrics

- Story points: completed vs planned
- Bug discovery rate
- Velocity: current vs average
- Scope change percentage
- Risk indicators

### Visualizations

```yaml
burndown_chart:
  type: line
  x_axis: days
  y_axis: story_points

velocity_trend:
  type: bar
  periods: last_6_sprints
```

### Output

`.bmad-workspace/ck-jira-integration/reports/sprint/sprint-health-{{sprint_name}}-YYYY-MM-DD.md`

[[LLM: Log: report_completed event with:

- report_type='sprint_health'
- generation_time
- metrics_included
- insights_generated
  ]]

## Roadmap Reports

[[LLM: Log: report_initiated event with type='roadmap']]
[[LLM: Track: which mode is being used (bmad/jira/reconciliation)]]

[[LLM: MANDATORY - Write roadmap report to file:

1. Generate complete roadmap report
2. Create directory: `mkdir -p .bmad-workspace/ck-jira-integration/reports/roadmap/`
3. Save to: `.bmad-workspace/ck-jira-integration/reports/roadmap/roadmap-YYYY-MM-DD.md`
4. Confirm: "✅ Roadmap report saved to: {{full_path}}"
   ]]

### Adaptive Modes

**BMAD Mode** (No JIRA):

- Parse story files for estimates
- Group by epic/theme
- Apply velocity assumptions
- Generate tentative timeline

[[LLM: If BMAD mode used, log: bmad_only_roadmap event]]

**JIRA Mode** (Active Project):

- [[LLM: Query epics, versions, milestones]]
- Use actual velocity
- Include dependencies
- Risk-adjusted timeline

**Reconciliation Mode** (Both):

- Compare planned vs actual
- Calculate variance
- Learn from patterns
- Adjust future estimates

### Visualization Options

- Timeline view
- Gantt chart
- Now/Next/Later
- Swimlanes by team
- Dependency graph

### Output

`.bmad-workspace/ck-jira-integration/reports/roadmap/roadmap-YYYY-MM-DD.md`

## Team Performance Reports

[[LLM: MANDATORY - Write team report to file:

1. Generate complete team performance report
2. Create directory: `mkdir -p .bmad-workspace/ck-jira-integration/reports/team/`
3. Save to: `.bmad-workspace/ck-jira-integration/reports/team/team-performance-YYYY-MM-DD.md`
4. Confirm: "✅ Team performance report saved to: {{full_path}}"
   ]]

### Metrics Collection

- Individual contributions
- [[LLM: Use JIRA assignee data + git commits:
  1. Load jira-expansion-config.yaml for all repositories
  2. For each repo, run: `git shortlog -sn --since="30 days ago"`
  3. Match Git authors to JIRA users
  4. Analyze commits per developer across all repos
     ]]
- Work distribution
- Collaboration patterns
- Skill utilization

### Analytics

- Productivity trends
- Workload balance
- Burnout indicators
- Team health score
- Growth opportunities

### Output

`.bmad-workspace/ck-jira-integration/reports/team/team-performance-YYYY-MM-DD.md`

## Quality Reports

[[LLM: MANDATORY - Write quality report to file:

1. Generate complete quality metrics report
2. Create directory: `mkdir -p .bmad-workspace/ck-jira-integration/reports/quality/`
3. Save to: `.bmad-workspace/ck-jira-integration/reports/quality/quality-metrics-YYYY-MM-DD.md`
4. Confirm: "✅ Quality report saved to: {{full_path}}"
   ]]

### Data Analysis

- [[LLM: Search for bugs with JQL: "issuetype = Bug"]]
- Bug introduction rate
- Resolution velocity
- Severity distribution
- Root cause patterns

### Insights

- Quality trends
- Risk hotspots
- Test coverage gaps
- Process improvements
- Prevention strategies

### Output

`.bmad-workspace/ck-jira-integration/reports/quality/quality-metrics-YYYY-MM-DD.md`

## Correlation Reports

[[LLM: MANDATORY - Write correlation report to file:

1. Generate complete three-way sync correlation report
2. Create directory: `mkdir -p .bmad-workspace/ck-jira-integration/reports/correlation/`
3. Save to: `.bmad-workspace/ck-jira-integration/reports/correlation/three-way-sync-YYYY-MM-DD.md`
4. Confirm: "✅ Correlation report saved to: {{full_path}}"
   ]]

### Three-Way Analysis

[[LLM: MANDATORY - Load Git configuration from JIRA expansion config:

1. Get all configured repositories from jira-expansion-config.yaml
2. Use git.flow.main_branch and develop_branch for analysis
3. Analyze commits from ALL repositories, not just primary
4. Include submodules if configured

CRITICAL: You MUST calculate ACTUAL percentages, not placeholders!
]]

**Git ↔ JIRA** (CALCULATE REAL NUMBERS):

- [[LLM: For each repository in config, run: `git log --oneline --grep="{{project_key}}-" --since="30 days ago"`]]
- Count total commits: `git log --oneline --since="30 days ago" | wc -l`
- Count commits with JIRA refs: `git log --oneline --grep="{{project_key}}-" --since="30 days ago" | wc -l`
- Calculate percentage: (jira_commits / total_commits) × 100
- Identify phantom tickets: JIRA issues in "Done" without commits
- Track orphaned commits: Commits without JIRA references

**JIRA ↔ BMAD** (CALCULATE REAL NUMBERS):

- List all BMAD stories: `find docs/epics -name "*.md" | wc -l`
- Count stories with JIRA refs in metadata
- Verify each JIRA ticket exists via MCP
- Calculate percentage: (stories_with_tickets / total_stories) × 100
- List missing tickets and orphaned stories

**Git ↔ BMAD** (CALCULATE REAL NUMBERS):

- For each story, search commits by filename/keywords
- Count stories with related git activity
- Calculate percentage: (stories_with_commits / total_stories) × 100
- Identify documentation drift and scope creep

### Health Scoring

```
EXAMPLE WITH REAL CALCULATION:
- Git↔JIRA: 45 of 60 commits have JIRA refs = 75%
- JIRA↔BMAD: 18 of 22 stories have tickets = 82%
- Git↔BMAD: 16 of 22 stories have commits = 73%
- Overall Health = (75 + 82 + 73) / 3 = 77%

Rating: 77% = Good (needs some attention)

NEVER show {{placeholders}} - always calculate real values!
```

### Output

`.bmad-workspace/ck-jira-integration/reports/correlation/three-way-sync-YYYY-MM-DD.md`

## Report Generation Workflow

[[LLM: MANDATORY workflow for EVERY report:

1. Detect report type needed
2. Check available data sources
3. Create directory using Bash tool: `mkdir -p .bmad-workspace/ck-jira-integration/reports/{{type}}/`
4. Gather data from available sources
5. Apply intelligence and analysis
6. Format complete report content with visual-ready data
7. Include recommendations and insights
8. **CRITICAL**: Use Write tool to save report to file:
   - Path: `.bmad-workspace/ck-jira-integration/reports/{{type}}/{{report-name}}-YYYY-MM-DD.md`
   - Content: The COMPLETE generated report
   - DO NOT skip this step!
9. **REQUIRED**: Confirm with message: "✅ Report saved to: {{full_file_path}}"
10. **OPTIONAL**: Also display a brief summary in chat if desired

NEVER skip step 8 - the Write tool MUST be used to save the report!
]]

## Advanced Features

### Scheduled Reports

- Daily standup prep (9 AM)
- Weekly team review (Monday)
- Sprint close analysis
- Monthly executive summary

### Comparative Analysis

- Period over period
- Team comparisons
- Project benchmarks
- Historical trends

### Predictive Analytics

- Completion probability
- Risk forecasting
- Capacity planning
- Quality predictions

### Export Formats

- Markdown (default)
- CSV data exports
- JSON for dashboards
- PDF ready layouts

## Quality Assurance

### Data Validation

- Verify freshness
- Check completeness
- Cross-reference sources
- Flag anomalies

### Insight Generation

- Identify patterns
- Surface risks
- Recommend actions
- Track improvements

## Examples

### Simple

User: "report"
_Detects sprint in progress → generates sprint health_

### Specific

User: "quality report for last month"
_Generates quality metrics with time range_

### Complex

User: "executive roadmap with risks"
_High-level roadmap with risk assessment_

### Analytical

User: "why is velocity dropping?"
_Deep dive team performance analysis_

This unified task replaces report-generate and report-roadmap, providing one intelligent reporting command that generates exactly the insights you need.