# Retro

> Engineering retrospective analyzing git history for velocity, work patterns, quality signals, and trends with persistent snapshots

- **Type:** Skill
- **Install:** `agentstack add skill-drag88-claude-dev-framework-retro`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [drag88](https://agentstack.voostack.com/s/drag88)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [drag88](https://github.com/drag88)
- **Source:** https://github.com/drag88/claude-dev-framework/tree/main/skills/retro

## Install

```sh
agentstack add skill-drag88-claude-dev-framework-retro
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# /retro — Engineering Retrospective

Generates a comprehensive engineering retrospective from git history. Surfaces velocity, patterns, and quality signals that are invisible in day-to-day work.

## When to Activate

- User types `/retro`
- User asks for "weekly metrics", "engineering stats", "how productive was I", "shipping velocity"

## Arguments

- `/retro` — default: last 7 days
- `/retro 24h` — last 24 hours
- `/retro 14d` — last 14 days
- `/retro 30d` — last 30 days
- `/retro compare` — compare current window vs prior same-length window
- `/retro compare 14d` — compare with explicit window

Validate argument format: number + `d`/`h`/`w`, or `compare` optionally followed by window. If invalid, show usage and stop.

## Instructions

### Step 1: Gather Raw Data

Fetch origin first, then run ALL git commands in parallel:

```bash
git fetch origin --quiet

# 1. Commits with stats
git log origin/main --since="" --format="%H|%ai|%s" --shortstat

# 2. Per-commit test vs production LOC (test/|spec/|__tests__/ = test files)
git log origin/main --since="" --format="COMMIT:%H" --numstat

# 3. Timestamps for session detection
git log origin/main --since="" --format="%at|%ai|%s" | sort -n

# 4. Hotspot analysis
git log origin/main --since="" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn

# 5. PR numbers from commit messages
git log origin/main --since="" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'
```

### Step 2: Compute Metrics

Present as summary table:

| Metric | Value |
|--------|-------|
| Commits to main | N |
| PRs merged | N |
| Total insertions | N |
| Total deletions | N |
| Net LOC added | N |
| Test LOC (insertions) | N |
| Test LOC ratio | N% |
| Active days | N |
| Detected sessions | N |
| Avg LOC/session-hour | N |

### Step 3: Commit Time Distribution

Hourly histogram with bar chart:
```
Hour  Commits  ████████████████
 00:    4      ████
 07:    5      █████
```

Call out: peak hours, dead zones, bimodal patterns, late-night clusters (after 10pm).

### Step 4: Work Session Detection

Detect sessions using **45-minute gap** between consecutive commits. Classify:
- **Deep sessions** (50+ min)
- **Medium sessions** (20-50 min)
- **Micro sessions** (= 14d)

Split into weekly buckets: commits, LOC, test ratio, fix ratio, session count.

### Step 10: Streak Tracking

Consecutive days with at least 1 commit, counting back from today:
```bash
git log origin/main --format="%ad" --date=format:"%Y-%m-%d" | sort -u
```

Display: "Shipping streak: N consecutive days"

### Step 11: Load History & Compare

Check for prior retro snapshots:
```bash
ls -t .context/retros/*.json 2>/dev/null
```

If prior retros exist, load most recent and show delta table:
```
                    Last        Now         Delta
Test ratio:         22%    →    41%         +19pp
Sessions:           10     →    14          +4
LOC/hour:           200    →    350         +75%
Fix ratio:          54%    →    30%         -24pp (improving)
```

If first retro, note: "First retro recorded — run again next week to see trends."

### Step 12: Save Retro History

```bash
mkdir -p .context/retros
```

Save JSON snapshot to `.context/retros/YYYY-MM-DD-N.json`:
```json
{
  "date": "2026-03-13",
  "window": "7d",
  "metrics": {
    "commits": 47,
    "prs_merged": 12,
    "insertions": 3200,
    "deletions": 800,
    "net_loc": 2400,
    "test_loc": 1300,
    "test_ratio": 0.41,
    "active_days": 6,
    "sessions": 14,
    "deep_sessions": 5,
    "avg_session_minutes": 42,
    "loc_per_session_hour": 350,
    "feat_pct": 0.40,
    "fix_pct": 0.30,
    "peak_hour": 22
  },
  "streak_days": 47,
  "tweetable": "Week of Mar 8: 47 commits, 3.2k LOC, 41% tests, 12 PRs, peak: 10pm"
}
```

### Step 13: Write the Narrative

Output directly to conversation (NOT to files except the JSON snapshot).

Structure:

**Tweetable summary** (first line):
```
Week of Mar 8: 47 commits, 3.2k LOC, 41% tests, 12 PRs, peak: 10pm | Streak: 47d
```

Then:
1. **Summary Table** (from Step 2)
2. **Trends vs Last Retro** (from Step 11, skip if first)
3. **Time & Session Patterns** — when productive hours are, session trends, estimated active hours/day
4. **Shipping Velocity** — commit type mix, PR size discipline, fix-chain detection, version bump discipline
5. **Code Quality Signals** — test ratio trend, hotspot churn, XL PRs that should have been split
6. **Focus & Highlights** — focus score with interpretation, ship of the week
7. **Top 3 Wins** — highest-impact things shipped, why they matter, what's impressive
8. **3 Things to Improve** — specific, actionable, anchored in actual commits
9. **3 Habits for Next Week** — small, practical, <5 minutes to adopt
10. **Week-over-Week Trends** (if applicable)

## Compare Mode

When `/retro compare` or `/retro compare 14d`:
1. Compute current window metrics using `--since`
2. Compute prior same-length window using `--since` and `--until` to avoid overlap
3. Side-by-side comparison table with deltas
4. Narrative highlighting biggest improvements and regressions
5. Save only current-window snapshot

## Tone

- Encouraging but candid, no coddling
- Specific — always anchor in actual commits/code
- Skip generic praise ("great job!") — say exactly what was good and why
- Frame improvements as leveling up, not criticism
- 2500-3500 words total
- Markdown tables and code blocks for data, prose for narrative

## Important Rules

- Use `origin/main` for all git queries (not local main)
- If zero commits in window, say so and suggest different window
- Round LOC/hour to nearest 50
- Treat merge commits as PR boundaries
- ALL narrative output goes to conversation — only file written is `.context/retros/` JSON
- On first run, skip comparison gracefully
- Do not read CLAUDE.md — this skill is self-contained

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [drag88](https://github.com/drag88)
- **Source:** [drag88/claude-dev-framework](https://github.com/drag88/claude-dev-framework)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-drag88-claude-dev-framework-retro
- Seller: https://agentstack.voostack.com/s/drag88
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.