sprint-retrospective

What this skill does

# Sprint Retrospective Expert

The agent acts as a data-driven retrospective facilitator that mines git history, PR metadata, and commit patterns to generate comprehensive sprint retrospective reports. It goes beyond simple commit counts — analyzing velocity trends, contributor work patterns, code health indicators, and team collaboration dynamics to surface actionable insights.

## Keywords

sprint retrospective, velocity analytics, contributor insights, code churn, work sessions, cycle time, lead time, throughput, burndown, team health, collaboration metrics, bus factor, refactor ratio, hotspot analysis, conventional commits, session detection, deep work, improvement tracking

## Quick Start

```bash
# 1. Sprint velocity analysis (last 14 days)
python scripts/velocity_analyzer.py --days 14 --format json > velocity.json

# 2. Contributor deep dive
python scripts/contributor_insights.py --days 14 --format json > contributors.json

# 3. Code churn analysis
python scripts/code_churn_analyzer.py --days 14 --format json > churn.json

# 4. Generate full retrospective report
python scripts/retro_report_generator.py \
  --velocity velocity.json \
  --contributors contributors.json \
  --churn churn.json \
  --sprint-name "Sprint 23" \
  --output retro_sprint_23.md

# One-liner: full pipeline
python scripts/velocity_analyzer.py --days 14 -f json > /tmp/v.json && \
python scripts/contributor_insights.py --days 14 -f json > /tmp/c.json && \
python scripts/code_churn_analyzer.py --days 14 -f json > /tmp/ch.json && \
python scripts/retro_report_generator.py -v /tmp/v.json -c /tmp/c.json -u /tmp/ch.json -s "Sprint 23"
```

## Core Workflows

### 1. Sprint Velocity Analysis

Analyze throughput, cycle time, and delivery patterns across the sprint window.

```bash
# Default: last 7 days
python scripts/velocity_analyzer.py

# Custom range
python scripts/velocity_analyzer.py --since 2026-03-04 --until 2026-03-18

# Compare against previous period
python scripts/velocity_analyzer.py --days 14 --compare-previous

# JSON output for pipeline
python scripts/velocity_analyzer.py --days 14 --format json
```

**Metrics computed:**

| Metric | Description |
|--------|-------------|
| Total Commits | Raw commit count in window |
| LOC Added / Removed / Net | Lines of code delta |
| PRs Merged | Pull requests merged (via merge commit detection) |
| Avg PR Size | Average lines changed per PR |
| Throughput | Commits per day |
| Cycle Time | Avg time from first commit on branch to merge |
| Lead Time | Avg time from commit to production (main branch) |
| Deploy Frequency | Merges to main per day |
| Commit Type Breakdown | feat/fix/docs/refactor/test/chore distribution |
| Hourly Distribution | Commit activity by hour of day |

**Session Detection:**

The analyzer detects work sessions using configurable gap thresholds:

| Session Type | Duration | Interpretation |
|-------------|----------|----------------|
| Deep Work | >50 min | Sustained focused coding |
| Focused | 20-50 min | Standard development sessions |
| Micro | <20 min | Quick fixes, reviews, hotfixes |

Gap threshold default: 45 minutes. Commits within the gap belong to the same session.

**Trend Comparison:**

When `--compare-previous` is enabled, the tool compares the current window against the immediately preceding window of equal length and computes deltas with directional indicators.

### 2. Contributor Deep Dive

Per-person analysis of contributions, work patterns, and specialization areas.

```bash
# All contributors, last 14 days
python scripts/contributor_insights.py --days 14

# Single contributor focus
python scripts/contributor_insights.py --days 14 --author "[email protected]"

# Include collaboration metrics
python scripts/contributor_insights.py --days 14 --collaboration
```

**Per-contributor metrics:**

- Commits, LOC added/removed, files touched
- Peak working hours (hourly heatmap)
- Session analysis (deep work ratio, session count)
- Focus areas by directory and file type
- Specialization detection: frontend / backend / infrastructure / docs / tests / data
- Consistency score (how evenly distributed are commits across the sprint)
- Collaboration: co-authored commits, cross-directory work

**Specialization Detection Rules:**

| Category | File Patterns |
|----------|--------------|
| Frontend | `*.tsx, *.jsx, *.vue, *.svelte, *.css, *.scss, *.html` |
| Backend | `*.py, *.go, *.rs, *.java, *.rb, *.php, *.cs` |
| Infrastructure | `Dockerfile, *.yml, *.yaml, terraform/*, k8s/*, .github/*` |
| Documentation | `*.md, *.rst, *.txt, docs/*` |
| Tests | `*test*, *spec*, __tests__/*` |
| Data | `*.sql, *.json, *.csv, migrations/*` |

### 3. Code Quality Trends

Identify churn hotspots, refactoring candidates, and code health indicators.

```bash
# Churn analysis
python scripts/code_churn_analyzer.py --days 14

# Top 20 hotspots
python scripts/code_churn_analyzer.py --days 14 --top 20

# Filter by directory
python scripts/code_churn_analyzer.py --days 14 --path src/

# Detect oscillation (files changed back and forth)
python scripts/code_churn_analyzer.py --days 14 --detect-oscillation
```

**Code Health Indicators:**

| Indicator | Calculation | Healthy Range |
|-----------|-------------|---------------|
| Churn Rate | Changes per file per day | <0.5 |
| Hotspot Concentration | % of changes in top 10% files | <40% |
| Test-to-Production Ratio | Test file changes / production file changes | >0.3 |
| Refactor Frequency | refactor commits / total commits | 10-25% |
| Oscillation Score | Files with >3 change-revert cycles | <5% of files |
| Directory Spread | Unique directories changed / total directories | Context-dependent |

**Hotspot Analysis:**

Files are ranked by a composite score: `changes * unique_authors * recency_weight`. High scores indicate files that are:
- Changed frequently (unstable or central)
- Touched by multiple people (potential conflict zone)
- Recently active (not historical noise)

### 4. Team Health Assessment

Evaluate collaboration patterns, review dynamics, and knowledge distribution.

```bash
# Team health from contributor data
python scripts/contributor_insights.py --days 14 --collaboration --format json
```

**Collaboration Metrics:**

| Metric | Description | Target |
|--------|-------------|--------|
| Review Coverage | % of PRs with at least one review | >90% |
| Cross-team PRs | PRs touching multiple team areas | Healthy: 10-30% |
| Knowledge Distribution | Files touched by only 1 person | <30% (bus factor) |
| Review Turnaround | Avg time from PR open to first review | <4 hours |
| Co-authored Commits | Commits with Co-authored-by trailers | Context-dependent |

**Bus Factor Analysis:**

For each directory, the tool computes how many contributors have touched files. Directories with only 1 contributor are flagged as knowledge silos.

### 5. Improvement Tracking

Track action items from previous retrospectives and measure follow-through.

```bash
# Generate report with action item tracking
python scripts/retro_report_generator.py \
  --velocity velocity.json \
  --contributors contributors.json \
  --churn churn.json \
  --previous-retro retro_sprint_22.md \
  --sprint-name "Sprint 23"

# Compare two sprints
python scripts/retro_report_generator.py \
  --velocity velocity_current.json \
  --contributors contributors_current.json \
  --churn churn_current.json \
  --previous-velocity velocity_previous.json \
  --sprint-name "Sprint 23"
```

The report generator extracts action items from previous retro reports (marked with `- [ ]` or `- [x]`) and includes a follow-through section showing completion status.

## Tools

| Tool | Purpose | Key Flags |
|------|---------|-----------|
| `velocity_analyzer.py` | Sprint throughput, cycle time, sessions | `--days`, `--since/--until`, `--compare-previous`, `--gap-minutes` |
| `contributor_insights.py` | Per-person metrics, specialization, patterns | `--days`, `--author`, `--collaboration` |
| `code_churn_analyzer.py` | File hotspots, chu