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 - <<'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

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

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

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:

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

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:

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.