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)

```bash
# 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:

```bash
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):
```bash
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:
```bash
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`.