name

engineering-retro

description

Git-based engineering retrospective analyzing commit history, PR patterns, and development velocity over a configurable time window. Use this skill when the user asks for a retrospective, retro, sprint review, weekly review, engineering review, development summary, commit analysis, team velocity report, or says "what did we ship", "what happened this week", "engineering retro", "sprint retro", "dev summary", "/engineering-retro". Supports time windows (7d default, 24h, 14d, 30d) and monorepo path scoping.

metadata

version

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:

Sort commits by author and timestamp
For each author, iterate chronologically — if gap between consecutive commits exceeds 2 hours, start a new session
Compute per-session: duration (first commit to last commit), commit count
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 count
Lines added / removed
Top 3 most-touched files
Primary commit types (from Step 6)
Number of sessions and average session length (from Step 5)

Frame this as contributor highlights — recognition of work done, not a ranking or performance metric. Order alphabetically by author name.

Step 11: Week-over-Week Comparison

Check for a prior snapshot in .engineering-retros/:

Find the most recent *.json file
If it exists and covers the adjacent prior window, compute deltas:
- Commit count delta (%)
- Lines changed delta (%)
- Contributor count delta
- Focus score delta
- Category distribution shift

If no prior snapshot exists, note this is the first retrospective and skip comparison.

Step 12: Save Snapshot

Save a JSON snapshot for future comparisons:

.engineering-retros/<YYYY-MM-DD>.json

Schema:

{
  "date": "YYYY-MM-DD",
  "window": "7d",
  "path_scope": null,
  "branch": "main",
  "timezone": "PST",
  "metrics": {
    "commits": 0,
    "contributors": 0,
    "files_changed": 0,
    "lines_added": 0,
    "lines_removed": 0,
    "net_delta": 0,
    "focus_score": 0.0
  },
  "categories": {},
  "hotspots": [],
  "sessions": {
    "total": 0,
    "avg_length_minutes": 0
  },
  "authors": {},
  "pr_stats": null
}

Create the .engineering-retros/ directory if it does not exist. Ensure .engineering-retros/ is in .gitignore (add it if missing — this is the one permitted file modification).

Step 13: Generate Narrative Summary

Produce the final output in this structure:

Engineering Retrospective — [DATE_RANGE] ([TIMEZONE]) Branch: [DEFAULT_BRANCH] | Scope: [PATH_SCOPE or "full repo"]

Metrics

Commits: N | Contributors: N | Files changed: N
Lines: +N / -N (net: +/-N)
Avg commit size: N lines | Focus score: N.NN

Time Patterns

Peak day: [DAY] | Peak hours: [RANGE]
[compact histogram]
Sessions: N total | Avg length: Nm | Longest: Nm

Work Breakdown

[category]: N commits (NN%)
...

Hotspots

path/to/file — N commits [HOTSPOT if >50%]
...

Contributor Highlights

[Author]: N commits, +N/-N lines, focused on [top files], primarily [categories]
...

PR Summary (if available)

Merged: N | Size dist: S/M/L/XL | Median review turnaround: Xh

Week-over-Week (if available)

Commits: +/-N% | Lines: +/-N% | Focus: +/-N.NN

Observations

[2-4 bullet points identifying patterns, achievements, and areas worth attention]
Based on data only — no speculation about intent or quality judgments about individuals

Constraints

Read-only: no code modifications, no branch changes, no git operations that alter state
No hardcoded timezone: always detect from date +%Z
No hardcoded branch: always detect dynamically via git symbolic-ref or git remote show
No individual performance judgments: author breakdown is for recognition, not evaluation
Path scope respected: all git commands must include -- $PATH_SCOPE when a scope is provided
Snapshot storage: .engineering-retros/ only, never .context/retros/

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Engineering Retrospective

Arguments

Execution Steps

Step 1: Environment Detection

Step 2: Gather Raw Git Data

Step 3: Compute Aggregate Metrics

Step 4: Time Distribution

Step 5: Session Analysis

Step 6: Commit Type Classification

Step 7: Hotspot Analysis

Step 8: PR Analysis

Step 9: Focus Score

Step 10: Per-Author Breakdown

Step 11: Week-over-Week Comparison

Step 12: Save Snapshot

Step 13: Generate Narrative Summary

Metrics

Time Patterns

Work Breakdown

Hotspots

Contributor Highlights

PR Summary (if available)

Week-over-Week (if available)

Observations

Constraints

FilesExpand file tree

SKILL.md

Latest commit

History

SKILL.md

File metadata and controls

Engineering Retrospective

Arguments

Execution Steps

Step 1: Environment Detection

Step 2: Gather Raw Git Data

Step 3: Compute Aggregate Metrics

Step 4: Time Distribution

Step 5: Session Analysis

Step 6: Commit Type Classification

Step 7: Hotspot Analysis

Step 8: PR Analysis

Step 9: Focus Score

Step 10: Per-Author Breakdown

Step 11: Week-over-Week Comparison

Step 12: Save Snapshot

Step 13: Generate Narrative Summary

Metrics

Time Patterns

Work Breakdown

Hotspots

Contributor Highlights

PR Summary (if available)

Week-over-Week (if available)

Observations

Constraints