Report Runner

Generate comprehensive project reports covering task execution, sprint progress, velocity metrics, and performance analysis in multiple output formats.

When to Use This Command

Run this command when...

• You need an executive summary, sprint report, or daily standup update generated from project data
• A sprint review meeting requires burndown charts, velocity metrics, and completion statistics
• You want to compile a status report that pulls data from git history, task state, and team activity
• You need to export project health metrics in markdown, JSON, or HTML format for stakeholders
• You want a retrospective-ready report analyzing what was delivered, what slipped, and why

Quick Start

Copy
# .claude/commands/report-runner.md
---
name: Report Runner
description: Generate project reports with metrics, progress, and analysis
command: true
---
Generate report: $ARGUMENTS

Supported report types:
- executive: High-level summary for stakeholders
- sprint: Detailed sprint progress with velocity
- standup: Quick daily status for team sync
- retrospective: Analysis of completed sprint for retro

Copy
# Invoke the command
claude "/report-runner sprint report for current week"

# Expected output
# > Collecting sprint data...
# >   Tasks completed: 12/18 (67%)
# >   Story points delivered: 34/52
# >   Velocity: 34 pts (avg: 38 pts)
# > Generating sprint report...
# > Report saved: reports/sprint-2026-W11.md
# >
# > Highlights:
# >   - Authentication module completed ahead of schedule
# >   - Database migration task carried over (blocked by staging env)
# >   - Team velocity 10% below 4-sprint average

Core Concepts

Concept	Description
Multi-Source Aggregation	Pulls data from git commits, task state, branch activity, and time logs
Report Templates	Pre-built formats for executive, sprint, standup, and custom reports
Metric Calculation	Computes velocity, burndown, lead time, cycle time, and throughput automatically
Trend Analysis	Compares current metrics against historical averages to identify patterns
Format Export	Outputs reports in markdown, JSON, or HTML for different consumption needs

Report Runner Data Pipeline
=============================

  [Git History]  [Task State]  [Time Logs]  [Branch Data]
       |              |             |              |
       v              v             v              v
  +--------------------------------------------------+
  |              Data Aggregation Layer               |
  +--------------------------------------------------+
                        |
              +---------+---------+
              |                   |
         [Calculate]         [Analyze]
         Velocity            Trends
         Burndown            Patterns
         Throughput          Blockers
              |                   |
              +---------+---------+
                        |
                  [Format Output]
                   md / json / html

Configuration

Parameter	Description	Default	Example	Required
$ARGUMENTS	Report type and time period	"sprint current"	"executive Q1 2026"	No
report_type	Type of report to generate	sprint	"executive", "standup"	No
output_format	Output file format	markdown	"json", "html"	No
compare_period	Historical period for trend comparison	last 3 sprints	"last 6 sprints"	No
include_blockers	Include blocker analysis section	true	false	No

Best Practices

1. Run standup reports daily -- Automate the standup report as part of your morning routine to have a ready-made update for team sync without manual compilation.

2. Use executive reports for stakeholder communication -- Executive summaries strip away technical details and focus on progress percentages, risks, and timelines that non-technical stakeholders need.

3. Compare against historical data -- Enable compare_period to show trends. A single sprint velocity number is meaningless without context; three-sprint averages reveal real patterns.

4. Export JSON for dashboards -- If your team uses a custom dashboard, export reports as JSON to feed data directly into visualization tools.

5. Generate retrospective reports before the meeting -- Having data-driven analysis ready before the retrospective focuses discussion on actionable improvements rather than memory-based anecdotes.

Common Issues

Incomplete data for new projects: Projects without sufficient git history or task tracking produce sparse reports. Ensure at least two weeks of tracked work before expecting meaningful trend analysis.

Mismatch between git and task state: If tasks are marked complete but commits reference different task IDs, the report may misattribute work. Keep task IDs consistent across commits and tracking tools.

Report generation slow on large repos: Repositories with thousands of commits can slow down git-based data collection. Limit the time window with specific date ranges rather than scanning the full history.