CODE-SAURABH/OpenSkills / retro-engineer
retro-engineer
VerifiedEngineering retrospective skill for continuous improvement. Use when the user wants to run a weekly or sprint retro, review shipping velocity, analyse test health trends, identify growth opportunities, get per-person breakdowns, or run a cross-project retrospective across all their AI tools and repos.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 22.1 KB |
SKILL.md
View on GitHub---
name: retro-engineer
description: Engineering retrospective skill for continuous improvement. Use when the user wants to run a weekly or sprint retro, review shipping velocity, analyse test health trends, identify growth opportunities, get per-person breakdowns, or run a cross-project retrospective across all their AI tools and repos.
---
# Retro Engineer Skill
## Overview
This skill guides you through a thorough, structured engineering retrospective. It operates in two distinct modes:
1. **Team Retro (Per-Person)** — Analyses a single repository, breaking down contributions by individual team members: what they shipped, velocity trends, test health, praise, and growth areas.
2. **Global Retro (Cross-Project)** — Spans all repositories and AI-assisted tools, producing a macro-level view of productivity, AI tool effectiveness, cross-project trends, and organisational health signals.
When in doubt about which mode to run, ask the user:
> Which retro mode would you like?
> - A) Team Retro — per-person breakdown for this repo/sprint
> - B) Global Retro — cross-project, all AI tools, all repos
---
## Step 0: Environment & Context Detection
Before starting any retro, gather environment context:
```bash
# Determine current repo
REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo "non-git")
REPO_SLUG=$(basename "$REPO_ROOT" 2>/dev/null || echo "global")
CURRENT_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
TODAY=$(date +%Y-%m-%d)
WEEK=$(date +%Y-W%V)
echo "REPO: $REPO_SLUG"
echo "BRANCH: $CURRENT_BRANCH"
echo "DATE: $TODAY"
echo "WEEK: $WEEK"
```
Identify the retro time window. Default is the last 7 days (weekly retro). If the user specifies a sprint length (e.g. 2 weeks, 4 weeks), use that window.
```bash
# Default: last 7 days
SINCE="7 days ago"
# For a 2-week sprint: SINCE="14 days ago"
# Always confirm with user if unclear
```
---
## Mode A: Team Retro (Per-Person Breakdown)
### Step A1: Collect Commit History
```bash
# Full commit log for the retro window with author details
git log \
--since="$SINCE" \
--format="%H|%an|%ae|%ad|%s" \
--date=short \
| sort > /tmp/retro_commits.txt
# Count commits per author
git shortlog \
--since="$SINCE" \
-sne \
| sort -rn > /tmp/retro_authors.txt
cat /tmp/retro_authors.txt
```
### Step A2: Collect PR & Branch Activity
```bash
# List recently merged branches (GitHub CLI if available)
if command -v gh &>/dev/null; then
gh pr list \
--state merged \
--json number,title,author,mergedAt,additions,deletions,changedFiles \
--limit 50 \
2>/dev/null | tee /tmp/retro_prs.json
else
# Fallback: list merged remote branches by date
git branch -r --merged main \
--sort=-committerdate \
| head -30
fi
```
### Step A3: Per-Person Contribution Breakdown
For each unique author found in `/tmp/retro_authors.txt`, produce:
```
### 👤 [Author Name]
**Commits:** N
**Files changed:** N
**Lines added:** +N | **Lines removed:** -N
**PRs merged:** N
**Avg PR size:** N lines
**Features shipped:**
- [List inferred from commit messages with feat: prefix]
**Bugs fixed:**
- [List inferred from commit messages with fix: prefix]
**Refactors / chores:**
- [List inferred from chore:, refactor:, test:, docs: prefixes]
**🌟 Praise (What went well):**
- [Highlight strong contributions, consistent commit quality, test coverage additions, documentation]
**📈 Growth Area:**
- [One respectful, actionable suggestion per person — e.g. commit message clarity, PR size, test coverage gaps]
```
To gather per-author file/line stats:
```bash
AUTHOR="[name]"
git log \
--since="$SINCE" \
--author="$AUTHOR" \
--format="%H" \
| xargs -I{} git diff-tree --no-commit-id -r --stat {} \
| tail -1
```
### Step A4: Shipping Streak Tracking
Shipping streaks celebrate consistency. A "shipping day" is any calendar day with at least one merged PR or production-meaningful commit (feat/fix).
```bash
# Generate list of shipping days
git log \
--since="$SINCE" \
--format="%ad" \
--date=short \
| sort -u > /tmp/shipping_days.txt
# Count streak (consecutive days)
python3 - <<'EOF'
from datetime import date, timedelta
with open("/tmp/shipping_days.txt") as f:
days = sorted(set(line.strip() for line in f if line.strip()))
if not days:
print("No shipping days found.")
else:
from datetime import datetime
dates = [datetime.strptime(d, "%Y-%m-%d").date() for d in days]
dates.sort(reverse=True)
streak = 1
for i in range(1, len(dates)):
if (dates[i-1] - dates[i]).days == 1:
streak += 1
else:
break
print(f"🔥 Current shipping streak: {streak} consecutive day(s)")
print(f"📦 Total shipping days this period: {len(dates)}")
print(f"Last shipped: {dates[0]}")
EOF
```
Render the shipping streak prominently in the retro report. If the streak is ≥ 5 days, call it out as an achievement worth celebrating.
### Step A5: Test Health Trend Analysis
```bash
# Discover test files changed
git log \
--since="$SINCE" \
--name-only \
--format="" \
| grep -E "(test|spec|__tests__|_test\.|\.test\.|\.spec\.)" \
| sort | uniq -c | sort -rn \
| head -20
# Count test files added vs deleted
TESTS_ADDED=$(git log --since="$SINCE" --diff-filter=A --name-only --format="" \
| grep -cE "(test|spec|__tests__|_test\.|\.test\.|\.spec\.)" 2>/dev/null || echo 0)
TESTS_DELETED=$(git log --since="$SINCE" --diff-filter=D --name-only --format="" \
| grep -cE "(test|spec|__tests__|_test\.|\.test\.|\.spec\.)" 2>/dev/null || echo 0)
echo "Test files added: $TESTS_ADDED"
echo "Test files deleted: $TESTS_DELETED"
```
Calculate a simple **Test Health Signal**:
| Signal | Meaning |
|--------|---------|
| Tests added > tests deleted | ✅ Health improving |
| Tests added == tests deleted | ⚠️ Neutral — no regression, no progress |
| Tests deleted > tests added | 🔴 Regression risk — investigate |
| Zero tests changed | ⚠️ No test activity — consider coverage goals |
If CI configuration is present (`.github/workflows`, `Jenkinsfile`, `.circleci`), note which pipelines ran and whether they passed:
```bash
# Check for CI config files
find . -maxdepth 3 \
-name "*.yml" -o -name "*.yaml" -o -name "Jenkinsfile" \
| grep -E "(github|ci|circleci|gitlab|jenkins)" \
| head -10
```
### Step A6: Velocity Metrics
Compile the full velocity table for the retro period:
```
## 📊 Velocity Metrics — [WEEK] — [REPO_SLUG]
| Metric | This Period | Prior Period | Δ |
|----------------------------|-------------|--------------|--------|
| Features shipped (feat:) | N | N | ±N |
| Bugs fixed (fix:) | N | N | ±N |
| PRs merged | N | N | ±N |
| Commits total | N | N | ±N |
| Test files added | N | N | ±N |
| Lines added | +N | +N | ±N |
| Lines removed | -N | -N | ±N |
| Active contributors | N | N | ±N |
| Avg PR cycle time (hrs) | N | N | ±N |
| Shipping days | N/7 | N/7 | ±N |
```
To gather "prior period" data for comparison:
```bash
PRIOR_SINCE="14 days ago"
PRIOR_UNTIL="7 days ago"
git log \
--after="$PRIOR_SINCE" \
--before="$PRIOR_UNTIL" \
--oneline \
| wc -l
```
---
## Mode B: Global Retro (Cross-Project & AI Tool Analysis)
### Step B1: Discover All Active Repos
```bash
# Common repo locations — expand as needed
find ~/code ~/projects ~/workspace ~/src ~/dev \
-maxdepth 3 \
-name ".git" \
-type d \
2>/dev/null \
| sed 's|/.git||' \
| sort > /tmp/retro_all_repos.txt
echo "Repos found:"
cat /tmp/retro_all_repos.txt
```
For each repo found, run a condensed version of Steps A1–A6 and aggregate results.
### Step B2: Cross-Project Shipping Summary
```
## 🌐 Global Shipping Summary — [WEEK]
| Repo | Commits | Features | Fixes | PRs | Active Contributors |
|-------------------|---------|----------|-------|-----|---------------------|
| repo-alpha | N | N | N | N | N |
| repo-beta | N | N | N | N | N |
| ... | ... | ... | ... | ... | ... |
| **TOTAL** | N | N | N | N | N (unique) |
```
Highlight the **top shipping repo** and the **repo with the most test activity**.
### Step B3: AI Tool Usage Breakdown
Scan for AI tool footprints across all repos:
```bash
# Check for AI-related config and history files
find ~ -maxdepth 4 \( \
-name ".claude" -o \
-name "CLAUDE.md" -o \
-name ".cursor" -o \
-name ".copilot" -o \
-name ".gstack" -o \
-name ".aider*" -o \
-name "*.prompt.md" \
\) -type f -o -type d \
2>/dev/null \
| head -40
```
Produce an AI tool usage breakdown table:
```
## 🤖 AI Tool Activity — [WEEK]
| AI Tool | Sessions / Files Detected | Repos Active In | Notable Usage |
|------------------|--------------------------|-----------------|--------------------------------|
| Claude / Beacon | N | N repos | [e.g. architecture, debugging] |
| GitHub Copilot | N | N repos | [e.g. autocomplete, PR review] |
| Cursor | N | N repos | [e.g. multi-file edits] |
| Aider | N | N repos | [e.g. commit automation] |
| Other | - | - | - |
```
Flag any repos with **zero AI tool activity** — these may benefit from onboarding.
### Step B4: Cross-Project Trends & Signals
Analyse and report on:
1. **Language diversity** — what languages are being written across all repos this period?
2. **Hotspot files** — files changed in 3+ repos (shared libraries, config templates)?
3. **Bus factor risk** — any repo where a single author made 100% of commits?
4. **Doc debt signal** — repos with commits but no `docs:` or README changes?
5. **Security signal** — any `fix:` commits mentioning auth, token, secret, cve, vuln?
```bash
# Bus factor check per repo
for repo in $(cat /tmp/retro_all_repos.txt); do
cd "$repo" 2>/dev/null || continue
TOTAL=$(git log --since="$SINCE" --oneline | wc -l | tr -d ' ')
TOP_AUTHOR=$(git shortlog --since="$SINCE" -sn | head -1)
TOP_COUNT=$(echo "$TOP_AUTHOR" | awk '{print $1}')
if [ "$TOTAL" -gt 0 ] && [ "$TOP_COUNT" -eq "$TOTAL" ]; then
echo "⚠️ Bus factor risk: $(basename $repo) — single author ($TOP_COUNT commits)"
fi
done
```
---
## Retro Report Format
Every retro (Team or Global) MUST produce a structured report in this format:
---
```markdown
# Engineering Retrospective — [REPO or GLOBAL] — [DATE]
**Period:** [START] → [END]
**Mode:** [Team / Global]
**Generated:** [TIMESTAMP]
---
## 🔥 Shipping Streak
[Streak badge and details]
---
## 📊 Velocity Metrics
[Velocity table from Step A6 / B2]
---
## 🧪 Test Health
[Test health signal + trend table]
---
## 👥 Per-Person Breakdown
[For Team mode: one section per author with praise + growth area]
[For Global mode: top contributors across all repos]
---
## ✅ What Went Well
1. [Achievement or win — be specific, name the person or team]
2. [...]
3. [...]
## 🔧 What to Improve
1. [Concrete, actionable issue — avoid blame, focus on process or system]
2. [...]
3. [...]
## 🚀 What to Try Next
1. [Experiment, new practice, or tool to trial in the next sprint]
2. [...]
3. [...]
---
## 🤖 AI Tool Usage
[AI tool breakdown table — Global mode only, or if AI tools detected]
---
## 📋 Action Items
| # | Action Item | Owner | Due Date | Priority |
|---|--------------------------------------|---------------|------------|----------|
| 1 | [Specific action] | [Name/@handle]| [YYYY-MM-DD] | High |
| 2 | [...] | [...] | [...] | Medium |
| 3 | [...] | [...] | [...] | Low |
---
## ✔️ Definition of Done — This Sprint
- [ ] All planned features are merged to main
- [ ] All P0/P1 bugs are resolved or have owners
- [ ] CI/CD pipeline is passing (no red builds at sprint close)
- [ ] Test coverage has not decreased from prior sprint baseline
- [ ] All PRs have at least one approver
- [ ] Release notes / changelog updated (if applicable)
- [ ] No open security-flagged `fix:` commits unreviewed
- [ ] Retro action items from prior sprint reviewed (done / carried / dropped)
- [ ] Documentation updated for any public API changes
- [ ] Bus factor risk addressed (pair programming, docs, or handoff scheduled)
---
## 📅 Next Retro
**Recommended cadence:** [Weekly for fast-moving teams | Bi-weekly for mature sprints | Monthly for maintenance repos]
**Next retro date:** [DATE + 7 or DATE + 14]
**Owner / facilitator:** [Name]
```
---
## Retro Cadence Recommendations
Use the following table to recommend the right retro cadence based on observed team velocity:
| Team Signal | Recommended Cadence |
|------------------------------------------|---------------------|
| >20 commits/week, active CI, 3+ contributors | Weekly |
| 10–20 commits/week, 2 contributors | Bi-weekly |
| <10 commits/week, solo or maintenance | Monthly |
| Post-incident or major release | Immediate / ad-hoc retro |
| New team or onboarding sprint | Weekly (first 4 weeks minimum) |
Always state the recommendation and reasoning in the retro report. Do not just pick weekly by default without checking the data.
---
## Action Item Standards
Every action item MUST follow this format when written:
```
| [#] | [Verb] + [specific outcome] — e.g. "Add E2E tests for checkout flow" | @[owner] | [YYYY-MM-DD] | [High/Medium/Low] |
```
Rules for action items:
- **Never write vague items** like "improve tests" or "fix CI". Be specific.
- **Every item must have an owner** — a named person or GitHub handle.
- **Due date is mandatory** — default to end of next sprint if not specified.
- **Maximum 5 action items per retro** — prioritise ruthlessly.
- **Start each retro by reviewing prior action items** before generating new ones.
To surface prior action items, check for a prior retro file:
```bash
ls -lt ~/.gstack/projects/"$REPO_SLUG"/retros/*.md 2>/dev/null | head -5
# or
find . -name "retro-*.md" -newer /tmp/dummy | head -5
```
---
## Shipping Streak — Extended Logic
A shipping streak is a series of consecutive calendar days (Mon–Fri, excluding weekends unless the team ships on weekends) where the team merged at least one production-meaningful unit of work.
**What counts as shipping:**
- A merged PR with label `feat`, `fix`, or `perf`
- A commit with a `feat:` or `fix:` prefix on the default branch
- A tagged release or version bump
**What does NOT count:**
- `chore:`, `docs:`, `test:` only days
- WIP or draft PRs
- Commits with `[skip ci]` or `[wip]`
Streaks are per-repo in Team mode and global-aggregate in Global mode.
Display streak with a visual indicator:
```
🔥🔥🔥 3-day streak
🔥🔥🔥🔥🔥 5-day streak — MILESTONE! Keep it up.
🔥×10 10-day streak — LEGENDARY.
```
If the streak was broken, note when it broke and why (if inferable from commit history).
---
## Test Health Trend — Extended Analysis
Beyond counting test files, perform a deeper health scan:
```bash
# Look for test coverage reports
find . -name "coverage.xml" -o -name "lcov.info" \
-o -name "coverage-summary.json" \
-o -name ".nyc_output" \
2>/dev/null | head -10
# Check if coverage decreased in this period
# (compare coverage badge or report if available)
```
Also scan for **anti-patterns** that indicate degrading test health:
```bash
# Tests that only skip
grep -r "\.skip\|xit\|xdescribe\|pytest.mark.skip" \
--include="*.test.*" --include="*.spec.*" \
-l . 2>/dev/null | head -10
# TODO in tests (unfinished tests)
grep -rn "TODO\|FIXME\|HACK" \
--include="*.test.*" --include="*.spec.*" \
. 2>/dev/null | wc -l
```
Report these as **Test Debt Signals** in the retro.
---
## Global Retro — AI Tool Effectiveness Score
For each AI tool detected, score its effectiveness (qualitative, based on evidence):
```
## 🤖 AI Tool Effectiveness — [WEEK]
| Tool | Evidence of Use | Output Quality Signal | Score (1–5) |
|--------------|--------------------------------------------|---------------------------------|-------------|
| AI agent | SKILL.md files, session logs detected | Commits with AI-attributed msgs | [score] |
| Copilot | .copilot config, PR review comments | Test coverage trend | [score] |
| Cursor | .cursor directory, multi-file diff patterns | Refactor commit frequency | [score] |
| Aider | aider.chat.md files, commit message patterns| Commit quality, conventional msg| [score] |
```
Scoring rubric:
- **5** — Clear productivity lift: more features, better test coverage, faster PRs
- **4** — Positive signal: consistent use, clean outputs, no regressions introduced
- **3** — Mixed signal: used but inconsistently, some regressions or noise commits
- **2** — Low signal: rarely used or outputs required heavy manual correction
- **1** — Negative signal: AI-generated code introduced bugs or tech debt
---
## Definition of Done — Full Checklist (Detailed)
This is the master DoD checklist. Include it in every retro. Check off items that are met; flag unchecked items as risks.
### Code Quality
- [ ] All code merged to default branch passes linting (ESLint, Pylint, Clippy, etc.)
- [ ] No new `FIXME` or `TODO` items introduced without a linked issue
- [ ] All functions/methods have docstrings or JSDoc (for public APIs)
- [ ] No dead code introduced (unused imports, unreachable branches)
- [ ] MISRA / CERT / coding standard violations resolved (if automotive/embedded context)
### Testing
- [ ] Unit tests written for all new functions (coverage ≥ prior baseline)
- [ ] Integration tests updated for changed API surfaces
- [ ] No test files have new `.skip` or `xit` entries without a tracking issue
- [ ] All tests pass locally and in CI
- [ ] Performance-sensitive code has benchmark tests
### CI/CD & Build
- [ ] CI pipeline green on default branch
- [ ] No secrets or credentials committed (secret scanning passed)
- [ ] Docker images build successfully (if applicable)
- [ ] Build artifacts are reproducible
- [ ] Deployment to staging succeeded (if applicable)
### Review & Process
- [ ] All PRs have at least 1 approving review
- [ ] No PR is older than the sprint window still open (or explicitly deferred)
- [ ] Commit messages follow Conventional Commits format
- [ ] Sprint board / backlog is up to date (done items closed, new items estimated)
### Documentation
- [ ] README updated for any new setup steps or environment variables
- [ ] CHANGELOG or release notes updated
- [ ] API documentation regenerated (if OpenAPI / Swagger / Javadoc driven)
- [ ] Architecture decision records (ADRs) written for significant design choices
### Security (Automotive & General)
- [ ] No new CVEs in updated dependencies (npm audit / pip audit / cargo audit)
- [ ] Authentication and authorisation logic reviewed
- [ ] Input validation present for all external data entry points
- [ ] Cryptographic operations use approved algorithms (no MD5, no hardcoded keys)
- [ ] (Automotive) UDS/CAN message handling validates all input lengths and ranges
### Handoff & Knowledge
- [ ] Bus factor risk addressed for any solo-authored critical component
- [ ] Onboarding docs updated if new tooling was added
- [ ] Prior sprint's retro action items reviewed and closed/carried/dropped
---
## Retro Facilitation Tips
When running this retro interactively with a team, follow these facilitation guidelines:
1. **Timebox each section** — What Went Well (10 min), What to Improve (15 min), What to Try Next (10 min), Action Items (10 min). Total: ~45 min.
2. **Start with data** — present the velocity metrics and test health before opinions. Let the data drive the conversation.
3. **No blame culture** — frame every "What to Improve" item as a system or process issue, not a person issue.
4. **Rotate facilitator** — each sprint, a different team member runs the retro. Log who facilitated in the retro file.
5. **Action items over discussion** — if a topic generates more than 5 minutes of discussion without converging, turn it into an action item and move on.
6. **Read prior action items first** — open every retro by reviewing the previous retro's action items. Mark each: ✅ Done, 🔄 Carry, ❌ Drop.
7. **Celebrate the streak** — always open with the shipping streak. Positive energy sets the tone.
---
## Saving the Retro Report
After generating the report, save it to a consistent location:
```bash
RETRO_DIR=~/.gstack/projects/"$REPO_SLUG"/retros
mkdir -p "$RETRO_DIR"
RETRO_FILE="$RETRO_DIR/retro-$TODAY.md"
# Write the report
cat > "$RETRO_FILE" << 'REPORT'
[generated report content]
REPORT
echo "✅ Retro saved to: $RETRO_FILE"
# Also write a local copy in the repo for team visibility (optional)
if [ -d "./.retros" ] || [ -f "./RETRO.md" ]; then
cp "$RETRO_FILE" "./.retros/retro-$TODAY.md" 2>/dev/null || true
fi
```
Also update the repo timeline:
```bash
echo "{\"event\":\"retro\",\"date\":\"$TODAY\",\"week\":\"$WEEK\",\"mode\":\"$RETRO_MODE\"}" \
>> ~/.gstack/projects/"$REPO_SLUG"/timeline.jsonl
```
---
## Summary Output Format
Always close the retro with a compact summary suitable for posting in Slack, Teams, or a standup channel:
```
📋 Retro Summary — [REPO] — [WEEK]
🔥 Shipping streak: N days
📦 Features shipped: N | 🐛 Bugs fixed: N | 🔀 PRs merged: N
🧪 Test health: [✅ Improving / ⚠️ Neutral / 🔴 Regressing]
👥 Active contributors: N
✅ Top win: [one sentence]
🔧 Top improvement: [one sentence]
🚀 Experiment next: [one sentence]
📋 Action items: N new | N carried from prior retro
📅 Next retro: [DATE]
```
This summary should be generated automatically at the end of every retro run.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| finishing-a-development-branchobra/superpowersUse when implementation is complete, all tests pass, and you need to decide how to integrate the work | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| systematic-debuggingobra/superpowersUse when encountering any bug, test failure, or unexpected behavior, before proposing fixes | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| test-driven-developmentobra/superpowersUse when implementing any feature or bugfix, before writing implementation code | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| skill-creatoranthropics/skillsCreate new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit, or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |