retro

--- name: retro description: "Sprint/project retrospective using git + GitHub metrics. Invoke when user says 'run retro', 'retrospective', 'what did we do this sprint', 'summarize last 2 weeks'. Fetches commits, merged PRs, closed issues, hotspot files, review patterns. Outputs structured retro: Wins / Learnings / Patterns / Recommendations. Optionally updates project knowledge files." allowed-tools: - Bash - Read - Write metadata: token-cost-tier: instruction token-cost-estimate: 3000 --- # /retro — Sprint Retrospective via Git + GitHub Metrics ## Usage ``` /retro [--since ] [--sprint ] [--output report|bullets|update-knowledge] ``` - `--since ` — time window (e.g., `"2 weeks ago"`, `2026-04-01`). Default: `"2 weeks ago"` - `--sprint ` — label for the sprint (e.g., `Sprint 12`). Optional, used in report header. - `--output report` — full structured retro report (default) - `--output bullets` — concise bullet list - `--output update-knowledge` — after report, append learnings to `.claude/knowledge/project/` --- ## Step 0 — Announce Plan ``` Retro Plan: 1. [cli] git metrics (~200 tok) 2. [cli] gh PR metrics (~300 tok) 3. [cli] hotspot files (~200 tok) 4. [instruction] synthesis + report (~2000 tok) Total: ~2700 tokens ``` --- ## Step 1 — Git Metrics ```bash # Commit count + authors in window git log --since="" --oneline --no-merges | wc -l git log --since="" --format="%an" --no-merges | sort | uniq -c | sort -rn | head -10 # Summary of commit activity git log --since="" --oneline --no-merges | head -30 ``` Extract: - Total commits - Active contributors + commit counts - Commit message patterns (feature/fix/chore/refactor distribution if parseable) --- ## Step 2 — PR Metrics ```bash # Merged PRs in window gh pr list --state merged --search "merged:>=$(date -d '' +%Y-%m-%d 2>/dev/null || date -v-14d +%Y-%m-%d)" --json number,title,additions,deletions,author,mergedAt --limit 30 2>/dev/null | head -50 # Open PRs at end of sprint (carry-over) gh pr list --state open --json number,title,createdAt,author --limit 10 2>/dev/null | head -30 ``` Extract: - Count of PRs merged - Avg PR size (additions + deletions) - Authors + PR counts - Any PRs still open (carry-over) **If `gh` is not available or not authenticated:** skip gh steps, note "gh not configured — PR metrics unavailable", continue with git-only data. --- ## Step 3 — Closed Issues ```bash gh issue list --state closed --search "closed:>=$(date -d '' +%Y-%m-%d 2>/dev/null || date -v-14d +%Y-%m-%d)" --json number,title,labels,closedAt --limit 30 2>/dev/null | head -40 ``` Extract: - Issue count closed - Label distribution (bug / feature / improvement / chore) - Recurring label patterns --- ## Step 4 — Hotspot Files ```bash git log --since="" --name-only --pretty=format: | grep -v '^$' | sort | uniq -c | sort -rn | head -10 ``` These are files that changed most frequently — likely high-churn areas deserving attention. --- ## Step 5 — Review Patterns (optional, if gh available) ```bash bash .claude/scripts/gh/hotspot-files.sh --since "" --top 5 2>/dev/null ``` Look for patterns in PR comments if persona files exist: ```bash ls .claude/personas/ 2>/dev/null ``` --- ## Step 6 — Synthesize ### If `--output report` (default): ``` # Retrospective: Date: | Window: → today ## Summary - commits by contributors - PRs merged | issues closed - Avg PR size: lines changed ## Wins - - ## Learnings - - ## Hotspot Files (most changed) | File | Changes | Signal | |------|---------|--------| | | | | ## Patterns - — e.g., "8 of 22 commits were hotfixes to auth module" - — e.g., "3 PRs opened but not merged — may need scope reduction" ## Recommendations - <1-3 concrete suggestions for next sprint based on observed patterns> ## What This Retro Can't Tell You - Team morale, blockers, communication quality — not in git data - Code quality trends — use /security-review or /code-review for that - Business impact — metrics measure activity, not outcomes ``` ### If `--output bullets`: ``` ## Retro: - commits | PRs merged | issues closed - **Hotspot:** - **Pattern:**

- **Next sprint:** ``` ### If `--output update-knowledge`: After producing the report, also append to `.claude/knowledge/project/agreement.md`: ```markdown ## Retro Notes — **Sprint:** **Key learnings:** - - **Agreed next steps:** - ``` Ask user: "Which of these learnings should be added to the project agreement?" before writing. Do not write without confirmation. --- ## Honesty Rules - **Never infer team morale or interpersonal dynamics from git data.** Git metrics measure activity, not quality. - **Hotspot files are not necessarily problem areas** — they may be high-value core files. Flag them as "frequently changed, worth watching" not "bad". - **"What this retro can't tell you" section is mandatory** — metrics are incomplete by nature. - **If gh is unavailable**, deliver git-only retro and note the gap clearly. --- ## Example ``` /retro --since "2 weeks ago" --sprint "Sprint 12" /retro --since 2026-04-01 --output update-knowledge /retro --since "1 month ago" --output bullets ```