retro

name	retro
description	Engineering retrospective — generates a data-driven report of development velocity, commit patterns, hotspots, and team insights from git history. Saves results for week-over-week comparison.

Clade for Codex

This workflow runs directly in Codex. Do not launch the claude CLI or delegate the workflow to Clade's MCP bridge.

Codex compatibility rules:

• Plugin skills are namespaced. Invoke this workflow explicitly as $clade:retro; a bare $name does not select the installed Clade plugin.
• Read the nearest AGENTS.md files for repository instructions. If a project has only CLAUDE.md, treat it as legacy project guidance and read it too.
• Store new Clade working state under .clade/ (or ~/.clade/ for personal state). Existing legacy Claude state may be read for migration, but do not create new vendor-specific state.
• A /skill-name reference means the corresponding Codex $clade:skill-name plugin skill, or the same workflow invoked naturally when explicit skill invocation is not available.
• Use Codex web, file, shell, image, and subagent capabilities when the source workflow names a vendor-specific tool. If a capability is unavailable, use the documented fallback instead of spawning another agent CLI.
• Paths such as <plugin-root>/... are relative to the installed Clade plugin containing this SKILL.md; resolve that root before invoking a helper.

Canonical Clade workflow

You are the Retro skill. You generate a data-driven engineering retrospective from git history.

Parse command

• /retro → last 7 days (default)
• /retro 24h → last 24 hours
• /retro 14d → last 14 days
• /retro 30d → last 30 days
• /retro compare → compare this period vs previous same-length period

---

Step 1: Gather raw data (run in parallel)

# Time window setup
SINCE="7 days ago"   # adjust based on arg

# Commit overview
git log --since="$SINCE" --oneline
git log --since="$SINCE" --format="%ae" | sort | uniq -c | sort -rn   # per-author

# Volume metrics
git log --since="$SINCE" --numstat --format="" | \
  awk 'NF==3 {add+=$1; del+=$2} END {print "+" add " -" del " lines"}'

# Commit timing (hour of day distribution)
git log --since="$SINCE" --format="%ad" --date=format:"%H" | sort | uniq -c

# Hotspot files (most changed)
git log --since="$SINCE" --name-only --format="" | sort | uniq -c | sort -rn | head -10

# Commit type breakdown (feat/fix/refactor/test/chore/docs)
git log --since="$SINCE" --oneline | \
  grep -oP '^[a-f0-9]+ \K(feat|fix|refactor|test|chore|docs|perf|ci|build)' | \
  sort | uniq -c | sort -rn

# Largest PRs / biggest changes
git log --since="$SINCE" --format="%H %s" | while read hash msg; do
  lines=$(git show --stat "$hash" | tail -1 | grep -oP '\d+ insertion' | grep -oP '\d+')
  echo "${lines:-0} $hash $msg"
done | sort -rn | head -5

---

Step 2: Compute metrics table

Metric	Value
Total commits	N
Active days	N / period_days
Lines added	+N
Lines removed	-N
Net LOC change	±N
Unique files changed	N
Fix ratio	fix_commits / total_commits %
Test commits	test_commits / total_commits %

Flags:

• Fix ratio > 50%: ⚠ High bug rate — more fixes than features
• Test ratio < 10%: ⚠ Low test coverage investment

---

Step 3: Work session analysis

Detect work sessions using 45-minute gap threshold between commits:

git log --since="$SINCE" --format="%at" | sort -n | python3 -c "
import sys
times = [int(l) for l in sys.stdin if l.strip()]
if not times: exit()
sessions = []
start = times[0]
prev = times[0]
for t in times[1:]:
    if t - prev > 2700:  # 45-min gap = new session
        sessions.append((start, prev))
        start = t
    prev = t
sessions.append((start, prev))
for s, e in sessions:
    dur = (e - s) // 60
    label = 'deep' if dur >= 50 else ('medium' if dur >= 20 else 'micro')
    print(f'{dur}min {label}')
"

Show:

Work sessions: N total
  Deep (50+ min): N  — sustained focus
  Medium (20-50 min): N
  Micro (<20 min): N  — quick fixes / reviews

---

Step 4: Commit pattern analysis

Hourly distribution (ASCII histogram):

Commits by hour:
00-06  ██ 3
06-12  ████████ 12
12-18  ████████████ 18
18-24  ██████ 9
Peak: 12:00-15:00

Type breakdown (bar chart):

feat      ████████████ 15
fix       ████████ 10   ← if >40%, flag
refactor  ████ 5
test      ██ 3
docs      █ 2
chore     █████ 6

---

Step 5: Hotspot analysis

Top 10 most-changed files:

  12 src/api/auth.ts         ← churn hotspot if >5 changes
   8 src/components/Table.tsx
   5 PROGRESS.md
   ...

Flag files changed 5+ times in the period as churn hotspots — they may need refactoring or clearer ownership.

---

Step 6: Ship of the week

Find the biggest single change (by LOC or conceptual scope):

git log --since="$SINCE" --format="%H %s" | head -20

Pick the one commit that represents the most significant user-visible change. Display:

🚀 Ship of the week: feat(auth): add OAuth2 Google login (abc1234)
   +847 -123 lines across 8 files

---

Step 7: Week-over-week trends (if compare flag or ≥ 14d range)

Compare this period vs the equivalent previous period:

                 This period    Previous    Δ
Commits          23             18          +28%  ↑
LOC added        +1,240         +890        +39%  ↑
Fix ratio        35%            48%         -13%  ↓ (fewer bugs)
Active days      6              5           +1    ↑

---

Step 8: Save retro history

Save a JSON snapshot for future comparisons:

mkdir -p .context/retros
# write JSON with metrics to .context/retros/YYYY-MM-DD.json

---

Step 9: Write the narrative

Lead with a 1-sentence tweetable summary, then the full report.

══════════════════════════════════════════════════════
RETRO: [project] — [date range]
══════════════════════════════════════════════════════

TL;DR: [one sentence — e.g., "Solid shipping week: 23 commits, OAuth shipped,
        fix rate dropped to 35% (down from 48% last week)."]

Metrics:    [table from Step 2]
Sessions:   [from Step 3]
Patterns:   [commit timing + type breakdown]
Hotspots:   [top files]
Ship of week: [Step 6]
Trends:     [if applicable]

What went well:
  - [specific example from git log, not generic praise]
  - ...

What to improve:
  - [specific pattern, e.g., "3 late-night commits that each needed a follow-up fix — try morning reviews"]
  - ...

Next week focus: [1-3 concrete suggestions based on the data]
══════════════════════════════════════════════════════

---

Completion Status

• ✅ DONE — retro report generated, history saved to .context/retros/
• ⚠ DONE_WITH_CONCERNS — limited git history for the period (fewer than 3 commits)
• ❌ BLOCKED — not in a git repository
• ❓ NEEDS_CONTEXT — specify a time range (e.g., /retro 14d)

Delivery completion

If this workflow changes files or external state:

• Inspect the real final state before responding, including git status for a repository task.
• Never report DONE while task-owned changes are uncommitted. Use or continue $clade:delivery and create a repository-compliant checkpoint or preserve the work when committing is unavailable.
• When the user request or trusted repository policy makes publication, deployment, or live verification part of the task, do not silently downgrade the result to local-only work.
• If a required delivery transition lacks authority, credentials, a destination, or reachable external state, report BLOCKED or NEEDS_CONTEXT rather than appending a "not committed/pushed/deployed" caveat after DONE.