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)