Team Retrospective

Produce a thorough engineering retrospective from commit history, working patterns, and code-quality metrics. The retro is team-aware: it figures out who is running it, then analyzes every contributor with concrete, commit-anchored praise and growth opportunities.

Gather context first

This skill ships standalone, so it can't assume your project's conventions, house style, or preferences the way it could for its author. Before doing the main work:

1. Auto-detect what you safely can from the repo — language/stack, base branch, build/test commands, existing config and docs. Never ask for something you can read for yourself.
2. Ask, don't assume, for the rest. Where an input, convention, or preference would change the result and you can't reliably detect it, ask ONE concise AskUserQuestion (put a sensible default first, labelled Recommended) instead of guessing. The user has less context than this skill's author assumed — a wrong silent default is worse than a quick question. Don't ask about things you can detect, and don't ask more than you need.

For this skill, confirm up front (only the items you can't already detect):

• Where to save snapshots & read trend history — defaults to ~/.claude/retros/. If the user keeps retros elsewhere, or that directory holds another project's history, confirm the path before writing the snapshot or computing "vs last retro" deltas against it.
• Commit-message convention — the type breakdown (Step 5), the fix-ratio flag, and the per-author type mix all assume conventional-commit prefixes (feat/fix/refactor/test/chore/docs). Sample the recent log; if this repo doesn't follow that scheme, ask how commits should be categorized rather than mislabeling everything chore.
• Regression-test commit markers — the defaults (test(qa):, test(design):, test: coverage) are a house convention, not universal. Confirm the repo's actual marker (or that there is none) before reporting a regression-test count.
• Window & scope — the analysis window (default last 7 days) and whether to scope to a single contributor, when not already supplied in $ARGUMENTS.

How this runs

By default the whole retro runs inline in the current conversation — the argument check, any clarifying questions about the window or person filter, all data gathering and metric computation, the snapshot write, and presenting the narrative. This is the cheap path and it is the default.

The retro is fundamentally a sequential pipeline: gather the raw git data once, then derive every metric from that single shared dataset. Steps 0–8 and 10–14 all read the same aggregate data and produce the snapshot, so run them in order in this context.

The one part that could be parallelized is Step 9 (per-contributor analysis) — each contributor is an independent pass over data you already have. That fan-out is opt-in only: before spawning any subagent or Workflow, stop and ask the user, for example:

This team has [N contributors] over [window]. I can analyze them one at a time inline here (cheaper, slower) or fan out [N] parallel agents (faster, more tokens). Which do you want?

Spawn subagents/workflows only after an explicit yes. If the user declines or doesn't answer, do the whole job inline.

Arguments

Check $ARGUMENTS:

• Default: last 7 days
• --days N — explicit window in days (e.g., --days 14, --days 30)
• 24h — last 24 hours
• 14d — last 14 days
• 30d — last 30 days
• --person <email> — scope analysis to a single contributor by email
• compare — compare the current window against the prior same-length window
• compare 14d — compare with an explicit window

Argument validation: If the argument is not a number followed by d, h, or w, or compare (optionally followed by a window), or --days N, print the usage block and stop:

Usage: team-retro [window | compare] [--person <email>]
  team-retro                    — last 7 days (default)
  team-retro 24h                — last 24 hours
  team-retro 14d                — last 14 days
  team-retro 30d                — last 30 days
  team-retro --days 14          — explicit window in days
  team-retro --person alice@x   — filter to single contributor
  team-retro compare            — compare this period vs prior period
  team-retro compare 14d        — compare with explicit window

Step 0: Detect Platform and Base Branch

Identify the git host from the remote URL:

git remote get-url origin 2>/dev/null

• URL contains github.com → GitHub
• URL contains gitlab → GitLab
• Otherwise probe CLI availability:
  • gh auth status 2>/dev/null succeeds → GitHub (covers GitHub Enterprise)
  • glab auth status 2>/dev/null succeeds → GitLab (covers self-hosted)
  • Neither → unknown (git-native commands only)

Resolve the default branch and use it as "the base branch" everywhere downstream.

If GitHub:

1. gh repo view --json defaultBranchRef -q .defaultBranchRef.name — use if it succeeds

If GitLab:

1. glab repo view -F json 2>/dev/null, extract default_branch — use if it succeeds

Git-native fallback:

1. git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|refs/remotes/origin/||'
2. If that fails: git rev-parse --verify origin/main 2>/dev/null → use main
3. If that fails: git rev-parse --verify origin/master 2>/dev/null → use master

If everything fails, default to main. Substitute the resolved branch name wherever the steps say <default>.

Instructions

Parse the argument into a time window, defaulting to 7 days. Report every time in the user's local timezone — use the system default and do NOT set TZ.

Midnight-aligned windows: For day (d) and week (w) units, compute an absolute start date at local midnight rather than a relative string. If today is 2026-04-17 and the window is 7 days, the start is 2026-04-10, passed as --since="2026-04-10T00:00:00" — the explicit T00:00:00 forces git to begin at midnight. For hour (h) units use --since="N hours ago", since midnight alignment is meaningless below a day.

Step 1: Gather Raw Data

Fetch origin and identify the current user:

git fetch origin <default> --quiet
git config user.name
git config user.email

Whatever git config user.name returns is "you" — the person reading this retro. Every other author is a teammate.

Run all of the data-gathering commands in parallel; they are independent:

# 1. All commits with metadata
git log origin/<default> --since="<start_date>T00:00:00" --format="%H|%aN|%ae|%ai|%s" --shortstat

# 2. Per-commit test vs production file breakdown
#    Each block starts with COMMIT:<hash>|<author>, followed by numstat lines.
#    Separate test files (matching test/|spec/|__tests__/) from production files.
git log origin/<default> --since="<start_date>T00:00:00" --format="COMMIT:%H|%aN" --numstat

# 3. Commit timestamps for session detection and hourly distribution
git log origin/<default> --since="<start_date>T00:00:00" --format="%at|%aN|%ai|%s" | sort -n

# 4. File hotspots (most frequently changed)
git log origin/<default> --since="<start_date>T00:00:00" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn

# 5. PR/MR numbers from commit messages (GitHub #NNN, GitLab !NNN)
git log origin/<default> --since="<start_date>T00:00:00" --format="%s" | grep -oE '[#!][0-9]+' | sort -t'#' -k1 | uniq

# 6. Per-author file focus
git log origin/<default> --since="<start_date>T00:00:00" --format="AUTHOR:%aN" --name-only

# 7. Per-author commit counts
git shortlog origin/<default> --since="<start_date>T00:00:00" -sn --no-merges

# 8. Test file count
find . -name '*.test.*' -o -name '*.spec.*' -o -name '*_test.*' -o -name '*_spec.*' 2>/dev/null | grep -v node_modules | wc -l

# 9. Regression test commits in window
git log origin/<default> --since="<start_date>T00:00:00" --oneline --grep="test(qa):" --grep="test(design):" --grep="test: coverage"

# 10. Test files changed in window
git log origin/<default> --since="<start_date>T00:00:00" --format="" --name-only | grep -E '\.(test|spec)\.' | sort -u | wc -l

If --person <email> was passed, append --author="<email>" to the git log commands above to scope the analysis to one contributor.

The --grep markers in command 9 (test(qa):, test(design):, test: coverage) are the author's house convention for regression-test commits, not a universal standard. Use whatever marker the repo actually uses — confirmed up front — or drop the regression-test count entirely if the repo has none, rather than reporting a misleading zero.

Step 2: Compute Metrics

Present a summary table:

Immediately below, show a per-author leaderboard:

Contributor         Commits   +/-          Top area
You (name)               32   +2400/-300   src/features/
alice                    12   +800/-150    src/components/
bob                       3   +120/-40     src/apis/

Sort by commits descending. The current user always comes first, labeled "You (name)".

Step 3: Commit Time Distribution

Hourly histogram in local time:

Hour  Commits  ████████████████
 00:    4      ████
 07:    5      █████
 09:    5      █████
 10:    8      ████████
 14:    12     ████████████
 ...

Call out:

• Peak hours
• Dead zones
• Whether the pattern is bimodal (morning/evening) or continuous
• Late-night coding clusters (after 10pm)

Step 4: Work Session Detection

Detect sessions using a 45-minute gap between consecutive commits as the boundary. For each session report:

• Start/end time (local)
• Number of commits
• Duration in minutes

Classify:

• Deep sessions (50+ min)
• Medium sessions (20–50 min)
• Micro sessions (<20 min, typically a single fire-and-forget commit)

Calculate:

• Total active coding time (sum of session durations)
• Average session length
• LOC per hour of active time

Step 5: Commit Type Breakdown

Categorize by conventional-commit prefix (feat/fix/refactor/test/chore/docs). This assumes the repo follows the conventional-commit scheme — sample the recent log first. If most commits have no recognizable prefix, don't silently bucket everything into chore; ask how the team categorizes commits (or note that this breakdown isn't meaningful for this repo) before rendering it. Render as a percentage bar:

feat:     20  (40%)  ████████████████████
fix:      27  (54%)  ███████████████████████████
refactor:  2  ( 4%)  ██

Flag when the fix ratio exceeds 50% — a "ship fast, fix fast" pattern that can signal review gaps.

Step 6: Hotspot Analysis

Top 10 most-changed files. Flag:

• Files changed 5+ times (churn hotspots)
• Test files vs production files in the hotspot list
• Ratio of test changes to code changes

Step 7: PR Size Distribution

Bucket PRs:

• Small (<100 LOC)
• Medium (100–500 LOC)
• Large (500–1500 LOC)
• XL (1500+ LOC) — flag with file counts

Step 8: Focus Score + Ship of the Week

Focus score: Share of commits touching the single most-changed top-level directory. Higher = deeper focused work; lower = scattered context-switching. Report it as: Focus score: 62% (src/features/).

Ship of the week: Auto-pick the single highest-LOC PR in the window:

• PR number and title
• LOC changed
• Why it matters (infer from commit messages and files touched)

Step 9: Team Member Analysis — per-contributor praise + growth

For each contributor (including the current user), compute:

1. Commits and LOC — total commits, insertions, deletions, net LOC
2. Areas of focus — top 3 directories/files they touched
3. Commit type mix — their personal feat/fix/refactor/test breakdown
4. Session patterns — peak hours, session count
5. Test discipline — their personal test LOC ratio
6. Biggest ship — their single highest-impact commit or PR in the window

For the current user ("You"): Give the deepest treatment. Include session analysis, time patterns, and focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."

For each teammate: Write 2–3 sentences on what they worked on and how they work. Then:

• Praise (1–2 specific things): Anchor it in actual commits. Not "great work" — say exactly what was good. Examples:
  • "Shipped the entire auth middleware rewrite in 3 focused sessions with 45% test coverage"
  • "Every PR under 200 LOC — disciplined decomposition"
  • "Fixed the N+1 query that was causing 2s load times on the dashboard"
• Opportunity for growth (1 specific thing): Frame it as leveling up, never criticism. Examples:
  • "Test ratio was 12% this week — adding tests to the payment module before it grows more complex would pay off"
  • "5 fix commits on the same file suggest the original PR could have used a review pass"
  • "All commits land between 1–4am — sustainable pace matters for code quality long-term"

Solo repo (one contributor): Skip the team breakdown entirely — the retro is personal. Write the personal deep-dive directly in this context.

Co-Authored-By trailers: Parse Co-Authored-By: lines in commit messages and credit those authors alongside the primary author. Track AI co-authors (e.g., noreply@anthropic.com) separately — count them as an "AI-assisted commits" metric, not as team members.

How to run the per-contributor analysis

Default (inline): Work through the contributors one at a time in this context. For each, derive their metrics from their slice of the Step 1 data and write their section directly. This is sequential but cheap, and the output is identical to the parallel path. Mark the current user as "You" and give that person the deepest, first-person treatment.

If the user opted into parallelism (see How this runs): each contributor is an independent pass, so you may fan out one agent per contributor as a Workflow and assemble the results back in this context. When you do, respect these constraints:

• Workflow agent() calls run in the background: they cannot call AskUserQuestion, talk to the user, or write files. Every question, all narrative presentation, and the ~/.claude/retros/ snapshot write stay in this context — the workflow only runs headless per-contributor compute and returns structured results.
• Always set model: 'opus' on agent() calls so a lightweight tier never leaks in.
• Pass each contributor's data in via args — Workflow scripts have no Date.now/Math.random/filesystem access, so timestamps, sequence numbers, and file writes all happen here in the main loop.
• Mark the current user with isYou: true so that agent produces the deepest, first-person treatment.

export const meta = {
  name: 'team-retro-team-analysis',
  description: 'Parallel per-contributor analysis — one agent per teammate produces praise + growth',
  phases: [{ title: 'Analyze' }],
}
const CONTRIBUTOR_SCHEMA = {
  type: 'object',
  properties: {
    name: { type: 'string' },
    isYou: { type: 'boolean' },
    commits: { type: 'number' },
    insertions: { type: 'number' },
    deletions: { type: 'number' },
    net_loc: { type: 'number' },
    test_ratio: { type: 'number' },
    focus_areas: { type: 'array', items: { type: 'string' } },
    type_mix: { type: 'string' },                                   // feat/fix/refactor/test breakdown
    session_pattern: { type: 'string' },                            // peak hours, session count
    biggest_ship: { type: 'string' },
    summary: { type: 'string' },                                    // 2-3 sentences (or first-person deep-dive for you)
    praise: { type: 'array', items: { type: 'string' } },           // 1-2 specific, commit-anchored
    growth: { type: 'array', items: { type: 'string' } },           // 1 specific, constructive
  },
  required: ['name', 'isYou', 'commits', 'summary', 'praise', 'growth'],
}
const analyses = await parallel(args.contributors.map(c => () =>
  agent(
    `You are analyzing ONE contributor's engineering activity for a team retro. ` +
    `Do NOT ask anything and do NOT write files — return findings only; the main loop assembles them.\n\n` +
    `CONTRIBUTOR: ${c.name}${c.isYou ? ' (this is the current user — "You")' : ''}\n` +
    `THEIR COMMIT DATA:\n${c.data}\n\n` +
    `SHARED CONTEXT: window=${args.window}; team aggregates=${args.aggregates}; ` +
    `focus-score basis=${args.focusBasis}.\n\n` +
    `Compute: commits and LOC (insertions/deletions/net); top-3 areas of focus; ` +
    `personal feat/fix/refactor/test commit-type mix; session patterns (peak hours, session count); ` +
    `personal test LOC ratio; and their single biggest ship (highest-impact commit or PR).\n` +
    (c.isYou
      ? `This is YOU — give the deepest treatment: session analysis, time patterns, focus score, ` +
        `framed in first person ("Your peak hours...", "Your biggest ship..."). ` +
        `Then "What you did well" (2-3 specific, commit-anchored) and "Where to level up" (1-2 specific, actionable).`
      : `Write a 2-3 sentence summary of what they shipped, focus areas, and commit patterns. ` +
        `Then Praise (1-2 specific things anchored in actual commits — not "great work", say exactly what was good) ` +
        `and one Opportunity for growth (specific, constructive, framed as a leveling-up investment, not criticism). ` +
        `Never compare this person against another teammate negatively — this section stands on its own.`),
    { label: `contributor:${c.key}`, phase: 'Analyze', model: 'opus', schema: CONTRIBUTOR_SCHEMA }
  )
))
return analyses.filter(Boolean)

Pass args: { window, aggregates, focusBasis, contributors: [{ key, name, isYou, data }, ...] }, where each contributor's data is the slice of the Step 1 git output (commits, numstat, timestamps, file focus, PR numbers) scoped to that author, and aggregates carries the team-wide numbers each agent needs for context. When the workflow returns, weave the isYou: true result into the "Your Week" personal deep-dive and the rest (sorted by commits descending) into the "Team Breakdown" section here. If the workflow fails or times out, fall back to computing each contributor's section sequentially inline.

Step 10: Week-over-Week Trends (if window ≥ 14d)

If the window is 14 days or more, split it into weekly buckets and show trends:

• Commits per week (total and per-author)
• LOC per week
• Test ratio per week
• Fix ratio per week
• Session count per week

Step 11: Streak Tracking

Count consecutive days with at least 1 commit to origin/<default>, walking backward from today. Track both a team streak and a personal streak:

# Team streak: all unique commit dates (local time) — no hard cutoff
git log origin/<default> --format="%ad" --date=format:"%Y-%m-%d" | sort -u

# Personal streak: only the current user's commits
git log origin/<default> --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u

This queries the full history, so streaks of any length report accurately. Show both:

• "Team shipping streak: 47 consecutive days"
• "Your shipping streak: 32 consecutive days"

Step 12: Load History & Compare

Before saving the new snapshot, look for prior retro history:

setopt +o nomatch 2>/dev/null || true  # zsh compat
ls -t ~/.claude/retros/*.json 2>/dev/null

If prior retros exist: Read the most recent one with the Read tool, compute deltas for the 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 and append: "First retro recorded — run again next week to see trends."

Step 13: Save Retro History

After computing every metric (including streaks) and loading any prior history for comparison, save a JSON snapshot. ~/.claude/retros/ is the default history location; if the user confirmed a different path up front (or trend history already lives elsewhere), use that path here and in Step 12 instead.

mkdir -p ~/.claude/retros

Determine the next sequence number for today:

setopt +o nomatch 2>/dev/null || true  # zsh compat
today=$(date +%Y-%m-%d)
existing=$(ls ~/.claude/retros/${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
next=$((existing + 1))
# Save as ~/.claude/retros/${today}-${next}.json

Use the Write tool to save the JSON with this schema:

{
  "date": "2026-04-17",
  "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": {
    "Your Name": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "src/features/" },
    "Alice": { "commits": 12, "insertions": 800, "deletions": 150, "test_ratio": 0.35, "top_area": "src/components/" }
  },
  "streak_days": 47,
  "tweetable": "Week of Apr 10: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm",
  "test_health": {
    "total_test_files": 47,
    "tests_added_this_period": 5,
    "regression_test_commits": 3,
    "test_files_changed": 8
  }
}

Only include test_health when test files were found (command 8 returns > 0). Omit any field with no data.

Step 14: Write the Narrative

Output Structure

Tweetable summary (the first line, before everything else):

Week of Apr 10: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d

Then structure the output as:

## Engineering Retro: [date range]

### Summary Table
(from Step 2)

### Trends vs Last Retro
(from Step 12, loaded before save — skip if first retro)

### Time & Session Patterns
(from Steps 3–4)

Narrative interpreting what the team-wide patterns mean:
- When the most productive hours are and what drives them
- Whether sessions are getting longer or shorter over time
- Estimated hours per day of active coding (team aggregate)
- Notable patterns: do team members code at the same time or in shifts?

### Shipping Velocity
(from Steps 5–7)

Narrative covering:
- Commit type mix and what it reveals
- PR size distribution and what it reveals about shipping cadence
- Fix-chain detection (sequences of fix commits on the same subsystem)

### Code Quality Signals
- Test LOC ratio trend
- Hotspot analysis (are the same files churning?)
- XL PR callouts

### Test Health
- Total test files: N
- Tests added this period: M
- Regression test commits: list `test(qa):`, `test(design):`, `test: coverage` commits
- If prior retro exists and has `test_health`: show delta "Test count: {last} → {now} (+{delta})"
- If test ratio < 20%: flag as growth area

### Focus & Highlights
(from Step 8)
- Focus score with interpretation
- Ship of the week callout

### Your Week (personal deep-dive)
(from Step 9, for the current user only)

- Personal commit count, LOC, test ratio
- Session patterns and peak hours
- Focus areas
- Biggest ship
- **What you did well** (2–3 specific things anchored in commits)
- **Where to level up** (1–2 specific, actionable suggestions)

### Team Breakdown
(from Step 9, for each teammate — skip if solo repo)

For each teammate (sorted by commits descending):

#### [Name]
- **What they shipped**: 2–3 sentences on contributions, focus areas, commit patterns
- **Praise**: 1–2 specific things, anchored in actual commits
- **Opportunity for growth**: 1 specific, constructive suggestion framed as investment

**AI collaboration note:** If many commits carry `Co-Authored-By` AI trailers, note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.

### Top 3 Team Wins
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
- What it was
- Who shipped it
- Why it matters (product/architecture impact)

### 3 Things to Improve
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."

### 3 Habits for Next Week
Small, practical, realistic. Each must be adoptable in under 5 minutes. At least one should be team-oriented (e.g., "review each other's PRs same-day").

### Week-over-Week Trends
(if applicable, from Step 10)

Compare Mode

When the user runs with compare (e.g., team-retro compare or team-retro compare 14d):

1. Compute metrics for the current window (default 7d) using a midnight-aligned start date
2. Compute metrics for the immediately prior same-length window using both --since and --until with midnight-aligned dates to avoid overlap (for a 7d window starting 2026-04-10, the prior window is --since="2026-04-03T00:00:00" --until="2026-04-10T00:00:00")
3. Show a side-by-side comparison table with deltas and arrows
4. Write a brief narrative highlighting the biggest improvements and regressions
5. Save only the current-window snapshot to ~/.claude/retros/; do not persist prior-window metrics

Tone

• Encouraging but candid — no coddling
• Specific and concrete — always anchor in actual commits/code
• Skip generic praise ("great job!") — say exactly what was good and why
• Frame improvements as leveling up, not criticism
• Praise should feel like something you'd actually say in a 1:1 — specific, earned, genuine
• Growth suggestions should feel like investment advice — "this is worth your time because..." not "you failed at..."
• Never compare teammates against each other negatively. Each person's section stands on its own
• Keep total output around 3000–4500 words (longer to accommodate team sections)
• Use markdown tables and code blocks for data, prose for narrative
• Output directly to the conversation — the only file written is the ~/.claude/retros/ JSON snapshot

Important Rules

1. ALL narrative output goes directly to the user in the conversation. The ONLY file written is the ~/.claude/retros/ JSON snapshot.
2. Use origin/<default> for all git queries (not the local branch, which may be stale).
3. Display all timestamps in the user's local timezone (do not override TZ).
4. If the window has zero commits, say so and suggest a different window.
5. Round LOC/hour to the nearest 50.
6. Treat merge commits as PR boundaries.
7. On first run (no prior retros), skip comparison sections gracefully.
8. This skill is self-contained — do not read CLAUDE.md or other project docs.
9. The whole retro runs inline by default; the per-contributor team analysis fans out to a Workflow only after the user explicitly opts in (see How this runs). Even when it fans out, never put a question, narrative presentation, or the ~/.claude/retros/ snapshot write inside a Workflow agent() — background agents cannot talk to the user or write files. Always set model: 'opus' on agent() calls.