Engineering Retrospective

---

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:

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

Compare Mode

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

1. Compute metrics for the current window (e.g., last 7 days)
2. Compute metrics for the prior window of the same length (e.g., 7–14 days ago)
3. Render a side-by-side table with deltas and directional arrows (↑/↓/→)
4. Write a narrative on improvements and regressions
5. 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