Engineering Retro

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:

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