Retro Engineer

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:

# 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.

# 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

# 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

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

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).

# Generate list of shipping days
git log \
  --since="$SINCE" \
  --format="%ad" \
  --date=short \
  | sort -u > /tmp/shipping_days.txt

# Count streak (consecutive days)
python3 - /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:

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

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

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

# 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?

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

---

# 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 | | /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:

# 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 (s

…

Source & license

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

• Author: CODE-SAURABH
• Source: CODE-SAURABH/OpenSkills
• License: MIT

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