name: retro description: | Weekly engineering retrospective. Analyzes commit history, work patterns, and code quality metrics with persistent history and trend tracking. Use when asked for a retro, retrospective, weekly review, shipping velocity, or engineering metrics. Trigger with /retro.

Generates a comprehensive engineering retrospective analyzing commit history, work patterns, and code quality metrics.

Arguments

/retro — default: last 7 days
/retro 24h — last 24 hours
/retro 14d — last 14 days
/retro 30d — last 30 days
/retro compare — compare current vs prior same-length window
/retro compare 14d — compare with explicit window

Instructions

Parse the argument for time window. Default to 7 days. Validate format: a number followed by d, h, or w, or the keyword compare with an optional window. If the format is invalid, show usage and stop.

Auto-detect default branch:

DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
DEFAULT_BRANCH=${DEFAULT_BRANCH:-main}

Use origin/$DEFAULT_BRANCH for all git queries.

Step 1: Gather Raw Data

Run all of the following via bash, in parallel:

# Commits with timestamps
git log origin/$DEFAULT_BRANCH --since="<window>" --format="%H|%ai|%s" --shortstat

# Per-commit test vs production LOC
git log origin/$DEFAULT_BRANCH --since="<window>" --format="COMMIT:%H" --numstat

# Timestamps for session detection (Pacific time)
TZ=America/Los_Angeles git log origin/$DEFAULT_BRANCH --since="<window>" --format="%at|%ai|%s" | sort -n

# Hotspot files
git log origin/$DEFAULT_BRANCH --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn

# PR numbers from commit messages
git log origin/$DEFAULT_BRANCH --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sort -un

Step 2: Compute Metrics

Build a summary table with the following columns:

| Metric | Value | |---|---| | Commits | — | | PRs merged | — | | Insertions | — | | Deletions | — | | Net LOC | — | | Test LOC | — | | Test ratio | — | | Version range | — | | Active days | — | | Detected sessions | — | | Avg LOC/session-hour | — |

Compute each metric from the raw data gathered in Step 1. Test LOC is determined by counting insertions in files matching common test patterns (*_test.*, *.test.*, *_spec.*, *.spec.*, test_*, tests/, __tests__/, etc.). Test ratio = test LOC / total insertions.

Step 3: Commit Time Distribution

Build an hourly histogram of commit times in Pacific time. Render as a bar chart using Unicode block characters. Call out:

Peak hours — the 2-3 hours with the most commits
Dead zones — any 4+ hour gap with zero commits
Bimodal patterns — two distinct activity peaks (e.g., morning + evening)
Late-night clusters — commits between midnight and 4am

Step 4: Work Session Detection

Group commits into sessions using a 45-minute gap threshold — any gap of 45+ minutes between consecutive commits starts a new session.

Classify each session:

Deep — 50+ minutes
Medium — 20–50 minutes
Micro — under 20 minutes

Calculate and report:

Total active time (sum of session durations)
Average session length
LOC per hour (net LOC / total active hours)

Step 5: Commit Type Breakdown

Categorize commits by conventional commit prefix: feat, fix, refactor, test, chore, docs, and other for anything that doesn't match.

Render a percentage bar chart. Flag a warning if fix ratio exceeds 50%.

Step 6: Hotspot Analysis

List the top 10 most-changed files by number of commits touching them.

Flag:

Churn — files with 5+ changes in the window
Test vs production ratio — whether hot files have corresponding test files that are also active

Step 7: PR Size Distribution

Classify PRs by total LOC changed (insertions + deletions):

| Size | LOC Range | |---|---| | Small | < 100 | | Medium | 100–500 | | Large | 500–1500 | | XL | 1500+ |

Flag any XL PRs with their file counts and summaries.

Step 8: Focus Score + Ship of the Week

Focus Score = percentage of commits in the single most-changed top-level directory. Higher is more focused.

Ship of the Week = the PR (or largest single commit) with the highest net LOC. Include its title and a one-line summary.

Step 9: Week-over-Week Trends

Only include this section if the time window is 14 days or longer.

Break the window into weekly buckets and show trends for:

Commits per week
LOC per week
Test ratio per week
Fix ratio per week
Sessions per week

Step 10: Streak Tracking

TZ=America/Los_Angeles git log origin/$DEFAULT_BRANCH --format="%ad" --date=format:"%Y-%m-%d" | sort -u

Count consecutive days with commits, walking backward from today. Report the current streak length.

Step 11: Load History & Compare

Use glob to search for: .context/retros/*.json

If found: use view to read the most recent file. Calculate deltas between current and previous metrics for the trends section.
If first run: skip comparison and note: "First retro — run again next week for trends."

Step 12: Save Retro History

mkdir -p .context/retros

Use the create tool to save a JSON snapshot to .context/retros/${today}-${seq}.json where ${today} is the current date in YYYY-MM-DD format and ${seq} is an incrementing number if multiple retros run on the same day.

Schema:

{
  "date": "2026-03-12",
  "window": "7d",
  "metrics": {
    "commits": 47,
    "prs_merged": 12,
    "insertions": 3200,
    "deletions": 800,
    "net_loc": 2400,
    "test_loc": 1300,
    "test_ratio": 0.41,
    "active_days": 6,
    "sessions": 14,
    "deep_sessions": 5,
    "avg_session_minutes": 42,
    "loc_per_session_hour": 350,
    "feat_pct": 0.40,
    "fix_pct": 0.30,
    "peak_hour": 22
  },
  "version_range": ["1.0.0", "1.1.0"],
  "streak_days": 47,
  "tweetable": "Week of Mar 8: 47 commits, 3.2k LOC, 41% tests, 12 PRs, peak: 10pm"
}

Step 13: Narrative Output

Structure the final output as follows:

Tweetable summary — one-line headline as the very first line
Summary Table — the metrics table from Step 2
Trends vs Last Retro — deltas from Step 11 (if history exists)
Time & Session Patterns — narrative interpretation of Steps 3–4
Shipping Velocity — commit type mix, PR size discipline, fix chains
Code Quality Signals — test ratio assessment, hotspot warnings, XL PR flags
Focus & Highlights — focus score, ship of the week
Top 3 Wins — best accomplishments from the window, anchored in specific commits/PRs
3 Things to Improve — specific, actionable, anchored in the data
3 Habits for Next Week — small, practical, each takes less than 5 minutes to adopt
Week-over-Week — trend tables (if window ≥ 14d)

Compare Mode

When the user invokes /retro compare (with or without an explicit window):

Compute metrics for the current window (e.g., last 7 days)
Compute metrics for the prior window of the same length (e.g., 7–14 days ago)
Render a side-by-side table with deltas and directional arrows (↑/↓/→)
Write a narrative on improvements and regressions
Only save the current-window snapshot to .context/retros/

Tone

Encouraging but candid. Be specific and concrete — skip generic praise. Reference actual commits, PRs, and files. Target 2500–3500 words. Use markdown tables and code blocks for data, prose for narrative sections.

Rules

ALL output goes to the conversation, not to files — the only file written is the .context/retros/ JSON snapshot
Use origin/$DEFAULT_BRANCH for all git queries
Display all times in Pacific time
If zero commits are found in the window, say so clearly and suggest trying a different window
Round LOC/hour to the nearest 50

Engineering Retrospective

Recommended for