/engineering-retro

name: engineering-retro
description: 'Git-based engineering retrospective analyzing commits, PRs, and velocity over configurable windows with monorepo path scoping. Triggers on: "retrospective", "sprint retro", "weekly review", "what did we ship", "engineering retro", "dev summary", "commit analysis".'
metadata:
  version: 1.0.1
  category: review
  tags: [retrospective, velocity, git-analysis, sprint]
  difficulty: intermediate
  phase: ship

Engineering Retrospective

Generate a structured, git-based engineering retrospective for a configurable time window. This is a **read-only analysis** — no files are modified except the optional JSON snapshot.

Arguments

/engineering-retro [TIME_WINDOW] [PATH_SCOPE]

• **TIME_WINDOW** (optional): `24h`, `7d` (default), `14d`, `30d`
• **PATH_SCOPE** (optional): restrict analysis to a subdirectory (monorepo support), e.g. `services/api`

Examples:

• `/engineering-retro` — last 7 days, full repo
• `/engineering-retro 30d` — last 30 days, full repo
• `/engineering-retro 14d services/api` — last 14 days, scoped to `services/api/`

Execution Steps

Step 1: Environment Detection

Detect runtime context before any analysis:

# Default branch
DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
if [ -z "$DEFAULT_BRANCH" ]; then
  DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
fi

# System timezone
TZ_NAME=$(date +%Z)

# Time window — convert argument to --since format
# 24h → "24 hours ago", 7d → "7 days ago", 14d → "14 days ago", 30d → "30 days ago"

If `DEFAULT_BRANCH` detection fails, abort with an error — do not guess.

Step 2: Gather Raw Git Data

Collect commits within the time window on the detected default branch:

# All commits in window (with optional path scope)
git log origin/$DEFAULT_BRANCH --since="$SINCE" --format="%H|%aI|%aN|%s" -- $PATH_SCOPE

# Diff stats for the window
git log origin/$DEFAULT_BRANCH --since="$SINCE" --numstat --format="%H" -- $PATH_SCOPE

Capture: commit hash, author date (ISO), author name, subject line, files changed, insertions, deletions.

Step 3: Compute Aggregate Metrics

From the raw data, compute:

• **Total commits** in window
• **Unique contributors** (distinct author names)
• **Files changed** (unique file paths across all commits)
• **Lines added** (sum of insertions)
• **Lines removed** (sum of deletions)
• **Net delta** (added - removed)
• **Avg commit size** (total lines changed / total commits)

Step 4: Time Distribution

Analyze commit timestamps (converted to system timezone `$TZ_NAME`):

• **Commits by day of week**: Mon-Sun histogram
• **Commits by hour**: 0-23 histogram
• **Peak day**: day with most commits
• **Peak hours**: hours with most activity

Present as a compact text histogram.

Step 5: Session Analysis

Group commits into work sessions using a >2 hour gap as a session boundary:

1. Sort commits by author and timestamp 2. For each author, iterate chronologically — if gap between consecutive commits exceeds 2 hours, start a new session 3. Compute per-session: duration (first commit to last commit), commit count 4. Aggregate: total sessions, average session length, longest session, average commits per session

Sessions with a single commit get a default duration of 0 (point-in-time).

Step 6: Commit Type Classification

Classify each commit using conventional commit prefixes from the subject line:

| Prefix pattern | Category | | ----------------------------------- | -------- | | `feat:`, `feat(` | feature | | `fix:`, `fix(`, `bugfix` | fix | | `refactor:`, `refactor(` | refactor | | `chore:`, `chore(`, `build:`, `ci:` | chore | | `docs:`, `doc:` | docs | | `test:`, `tests:` | test | | `perf:` | perf | | `style:` | style |

For commits without conventional prefixes, apply diff heuristics:

• Primarily new files added → feature
• Primarily deletions → refactor
• Test files only → test
• Config/CI files only → chore
• Documentation files only → docs
• Otherwise → uncategorized

Report counts and percentages per category.

Step 7: Hotspot Analysis

Identify the **top 10 most-modified files** by number of commits touching them:

git log origin/$DEFAULT_BRANCH --since="$SINCE" --name-only --format="" -- $PATH_SCOPE | sort | uniq -c | sort -rn | head -20

Flag any file modified in **>50% of total commits** as a hotspot. Hotspots indicate:

• Active area of development (expected during feature work)
• Potential coupling issues (if unrelated commits keep touching the same file)
• Possible need for decomposition (if the file is large)

Step 8: PR Analysis

If the remote is GitHub (check `git remote get-url origin` for `github.com`):

# Merged PRs in window
gh pr list --state merged --base $DEFAULT_BRANCH --search "merged:>=$SINCE_DATE" --json number,title,author,mergedAt,additions,deletions,changedFiles,reviews

Compute:

• **Total merged PRs**
• **Size distribution**: S (<50 lines), M (50-200), L (200-500), XL (>500)
• **Review turnaround**: time from PR creation to first review (median, p90)
• **Merge turnaround**: time from PR creation to merge (median, p90)

If not a GitHub remote or `gh` is unavailable, skip this step and note it in the output.

Step 9: Focus Score

Compute the ratio of **focused commits** (touching 3 or fewer files) to total commits:

focus_score = commits_touching_le_3_files / total_commits

Interpretation:

• **>0.8**: highly focused, small incremental changes
• **0.5-0.8**: moderate focus, mix of targeted and broad changes
• **<0.5**: broad changes dominating, may indicate large refactors or low commit discipline

Step 10: Per-Author Breakdown

For each contributor, report:

• Commit