name: retro version: 2.0.0 description: | Weekly engineering retrospective. Analyzes commit history, work patterns, and code quality metrics with persistent history and trend tracking. Team-aware: breaks down per-person contributions with praise and growth areas. allowed-tools:
_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
[ -n "$_UPD" ] && echo "$_UPD"
If output shows UPGRADE_AVAILABLE <old> <new>: read ~/.claude/skills/gstack/gstack-upgrade/SKILL.md and follow the "Inline upgrade flow" (AskUserQuestion → upgrade if yes, touch ~/.gstack/last-update-check if no). If JUST_UPGRADED <from> <to>: tell user "Running gstack v{to} (just updated!)" and continue.
Generates a comprehensive engineering retrospective analyzing commit history, work patterns, and code quality metrics. Team-aware: identifies the user running the command, then analyzes every contributor with per-person praise and growth opportunities. Designed for a senior IC/CTO-level builder using Claude Code as a force multiplier.
When the user types /retro, run this skill.
/retro — default: last 7 days/retro 24h — last 24 hours/retro 14d — last 14 days/retro 30d — last 30 days/retro compare — compare current window vs prior same-length window/retro compare 14d — compare with explicit windowParse the argument to determine the time window. Default to 7 days if no argument given. Use --since="N days ago", --since="N hours ago", or --since="N weeks ago" (for w units) for git log queries. All times should be reported in Pacific time (use TZ=America/Los_Angeles when converting timestamps).
Argument validation: If the argument doesn't match a number followed by d, h, or w, the word compare, or compare followed by a number and d/h/w, show this usage and stop:
Usage: /retro [window]
/retro — last 7 days (default)
/retro 24h — last 24 hours
/retro 14d — last 14 days
/retro 30d — last 30 days
/retro compare — compare this period vs prior period
/retro compare 14d — compare with explicit window
First, fetch origin and identify the current user:
git fetch origin main --quiet
# Identify who is running the retro
git config user.name
git config user.email
The name returned by git config user.name is "you" — the person reading this retro. All other authors are teammates. Use this to orient the narrative: "your" commits vs teammate contributions.
Run ALL of these git commands in parallel (they are independent):
# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
git log origin/main --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat
# 2. Per-commit test vs total LOC breakdown with author
# Each commit block starts with COMMIT:<hash>|<author>, followed by numstat lines.
# Separate test files (matching test/|spec/|__tests__/) from production files.
git log origin/main --since="<window>" --format="COMMIT:%H|%aN" --numstat
# 3. Commit timestamps for session detection and hourly distribution (with author)
# Use TZ=America/Los_Angeles for Pacific time conversion
TZ=America/Los_Angeles git log origin/main --since="<window>" --format="%at|%aN|%ai|%s" | sort -n
# 4. Files most frequently changed (hotspot analysis)
git log origin/main --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn
# 5. PR numbers from commit messages (extract #NNN patterns)
git log origin/main --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'
# 6. Per-author file hotspots (who touches what)
git log origin/main --since="<window>" --format="AUTHOR:%aN" --name-only
# 7. Per-author commit counts (quick summary)
git shortlog origin/main --since="<window>" -sn --no-merges
# 8. Greptile triage history (if available)
cat ~/.gstack/greptile-history.md 2>/dev/null || true
Calculate and present these metrics in a summary table:
| Metric | Value |
|---|---|
| Commits to main | N |
| Contributors | N |
| PRs merged | N |
| Total insertions | N |
| Total deletions | N |
| Net LOC added | N |
| Test LOC (insertions) | N |
| Test LOC ratio | N% |
| Version range | vX.Y.Z.W → vX.Y.Z.W |
| Active days | N |
| Detected sessions | N |
| Avg LOC/session-hour | N |
| Greptile signal | N% (Y catches, Z FPs) |
Then show a per-author leaderboard immediately below:
Contributor Commits +/- Top area
You (garry) 32 +2400/-300 browse/
alice 12 +800/-150 app/services/
bob 3 +120/-40 tests/
Sort by commits descending. The current user (from git config user.name) always appears first, labeled "You (name)".
Greptile signal (if history exists): Read ~/.gstack/greptile-history.md (fetched in Step 1, command 8). Filter entries within the retro time window by date. Count entries by type: fix, fp, already-fixed. Compute signal ratio: (fix + already-fixed) / (fix + already-fixed + fp). If no entries exist in the window or the file doesn't exist, skip the Greptile metric row. Skip unparseable lines silently.
Show hourly histogram in Pacific time using bar chart:
Hour Commits ████████████████
00: 4 ████
07: 5 █████
...
Identify and call out:
Detect sessions using 45-minute gap threshold between consecutive commits. For each session report:
Classify sessions:
Calculate:
Categorize by conventional commit prefix (feat/fix/refactor/test/chore/docs). Show as percentage bar:
feat: 20 (40%) ████████████████████
fix: 27 (54%) ███████████████████████████
refactor: 2 ( 4%) ██
Flag if fix ratio exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
Show top 10 most-changed files. Flag:
From commit diffs, estimate PR sizes and bucket them:
Focus score: Calculate the percentage of commits touching the single most-changed top-level directory (e.g., app/services/, app/views/). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
Ship of the week: Auto-identify the single highest-LOC PR in the window. Highlight it:
For each contributor (including the current user), compute:
For the current user ("You"): This section gets the deepest treatment. Include all the detail from the solo retro — session analysis, time patterns, focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."
For each teammate: Write 2-3 sentences covering what they worked on and their pattern. Then:
If only one contributor (solo repo): Skip the team breakdown and proceed as before — the retro is personal.
If there are Co-Authored-By trailers: Parse Co-Authored-By: lines in commit messages. Credit those authors for the commit alongside the primary author. Note AI co-authors (e.g., noreply@anthropic.com) but do not include them as team members — instead, track "AI-assisted commits" as a separate metric.
If the time window is 14 days or more, split into weekly buckets and show trends:
Count consecutive days with at least 1 commit to origin/main, going back from today. Track both team streak and personal streak:
# Team streak: all unique commit dates (Pacific time) — no hard cutoff
TZ=America/Los_Angeles git log origin/main --format="%ad" --date=format:"%Y-%m-%d" | sort -u
# Personal streak: only the current user's commits
TZ=America/Los_Angeles git log origin/main --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
Count backward from today — how many consecutive days have at least one commit? This queries the full history so streaks of any length are reported accurately. Display both:
Before saving the new snapshot, check for prior retro history:
ls -t .context/retros/*.json 2>/dev/null
If prior retros exist: Load the most recent one using the Read tool. Calculate deltas for key metrics and include a Trends vs Last Retro section:
Last Now Delta
Test ratio: 22% → 41% ↑19pp
Sessions: 10 → 14 ↑4
LOC/hour: 200 → 350 ↑75%
Fix ratio: 54% → 30% ↓24pp (improving)
Commits: 32 → 47 ↑47%
Deep sessions: 3 → 5 ↑2
If no prior retros exist: Skip the comparison section and append: "First retro recorded — run again next week to see trends."
After computing all metrics (including streak) and loading any prior history for comparison, save a JSON snapshot:
mkdir -p .context/retros
Determine the next sequence number for today (substitute the actual date for $(date +%Y-%m-%d)):
# Count existing retros for today to get next sequence number
today=$(TZ=America/Los_Angeles date +%Y-%m-%d)
existing=$(ls .context/retros/${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
next=$((existing + 1))
# Save as .context/retros/${today}-${next}.json
Use the Write tool to save the JSON file with this schema:
{
"date": "2026-03-08",
"window": "7d",
"metrics": {
"commits": 47,
"contributors": 3,
"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,
"ai_assisted_commits": 32
},
"authors": {
"Garry Tan": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "browse/" },
"Alice": { "commits": 12, "insertions": 800, "deletions": 150, "test_ratio": 0.35, "top_area": "app/services/" }
},
"version_range": ["1.16.0.0", "1.16.1.0"],
"streak_days": 47,
"tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm",
"greptile": {
"fixes": 3,
"fps": 1,
"already_fixed": 2,
"signal_pct": 83
}
}
Note: Only include the greptile field if ~/.gstack/greptile-history.md exists and has entries within the time window. If no history data is available, omit the field entirely.
Structure the output as:
Tweetable summary (first line, before everything else):
Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
(from Step 2)
(from Step 11, loaded before save — skip if first retro)
(from Steps 3-4)
Narrative interpreting what the team-wide patterns mean:
(from Steps 5-7)
Narrative covering:
(from Step 8)
(from Step 9, for the current user only)
This is the section the user cares most about. Include:
(from Step 9, for each teammate — skip if solo repo)
For each teammate (sorted by commits descending), write a section:
AI collaboration note: If many commits have Co-Authored-By AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
(if applicable, from Step 10)
When the user runs /retro compare (or /retro compare 14d):
--since="7 days ago"--since and --until to avoid overlap (e.g., --since="14 days ago" --until="7 days ago" for a 7d window).context/retros/ (same as a normal retro run); do not persist the prior-window metrics..context/retros/ JSON snapshot).context/retros/ JSON snapshot.origin/main for all git queries (not local main which may be stale)TZ=America/Los_Angeles)