garrytan / garrytan/gstack

Feature: Team-scoped /retro mode for multi-repo orgs

Open
#402 0 comments 0 reactions 0 assignees View on GitHub
Dominant language
TypeScript
Stars
133k
Forks
19.9k
Avg merge
18h 46m
Merged PRs (30d)
26

Description

## Summary

Add a `/retro team` mode that generates a **user-agnostic, team-focused** engineering retrospective across all repos in a directory. The current `/retro` and `/retro global` modes are personal — they orient around "you" (the person running the command). A team mode would orient around the org's collective output, designed to be shared in a team Slack channel or Monday standup.

## Rationale

### The gap today

`/retro global` does 90% of the work already — it discovers repos, gathers git data, computes streaks, context switching, and per-contributor breakdowns. But it's framed as a personal tool:

- The **shareable personal card** leads the output and only shows the current user's stats
- The narrative uses "your" framing throughout ("Your contributions", "Your Week")
- The contributor leaderboard puts "You (name)" first
- Per-project breakdowns include a "Your contributions" sub-section

For a team lead running retros for a Monday standup, this framing is wrong. They want:

1. **Equal treatment of all contributors** — no "you" vs "teammates" distinction
2. **Team-level metrics first** — total commits, LOC, streak, context switching across the org
3. **Per-person analysis that reads like a manager's 1:1 prep** — what each person shipped, praise, growth areas
4. **Week-over-week comparison** — "are we shipping more or less than last week?" is the #1 question
5. **Scoped to a folder** — not all AI session repos globally, just the repos that belong to this team/org

### Why this belongs in gstack (not a custom skill)

I built a standalone custom skill to solve this for my org (~15 repos, ~16 contributors across two timezones). It works, but:

- It **duplicates** most of `/retro`'s logic (repo discovery, git data gathering, streak calculation, hourly distribution, contributor aggregation)
- It **misses improvements** when `/retro` gets better
- The **data gathering patterns** are identical — the only difference is the framing and output structure
- Any team with a multi-repo setup would benefit from the same thing

### What I learned building it

1. **Multi-timezone coverage is a real pattern.** My team spans US and Asia timezones. The hourly histogram shows near-24h shipping coverage when normalized to one timezone. `/retro` doesn't call this out — a team mode should detect and highlight timezone distribution automatically.

2. **Context switching per day is the key team-health metric.** How many repos had commits on a given day reveals whether the team is focused or fragmented. `/retro global` computes this but buries it. In team mode it should be prominent.

3. **Week-over-week deltas are the #1 thing a manager wants.** Not absolute numbers — deltas. "Commits up 15%, test ratio down 3pp, one new contributor." The snapshot/compare infrastructure already exists in `/retro` — team mode just needs its own snapshot namespace.

4. **The personal card should be optional, not the lead.** In team mode, the summary table and contributor leaderboard should lead. No personal card at all.

## Proposed Design

### Invocation

```
/retro team — team retro, last 7 days, all repos in cwd
/retro team 14d — team retro, last 14 days
/retro team ~/org/ — team retro, repos in specified directory
```

### Behavior changes vs `/retro global`

| Aspect | `/retro global` | `/retro team` |
|--------|-----------------|---------------|
| Framing | Personal ("you") | Team (no "you") |
| Lead section | Personal shareable card | Summary table + leaderboard |
| Repo discovery | AI session history | All git repos in directory |
| Contributor treatment | Current user first | All equal, sorted by commits |
| Per-project "Your contributions" | Yes | No — just top contributors |
| Week-over-week comparison | Optional | Prominent (designed for weekly cadence) |
| Snapshot location | `~/.gstack/retros/` | `.context/team-retros/` (project-local) |
| Timezone analysis | Not called out | Auto-detect multi-TZ coverage |

### Shared infrastructure

Most of the implementation should be shared with `/retro global`:
- Repo discovery (generalized to "find git repos in directory")
- Git data gathering (commits, LOC, authors, timestamps, streaks)
- Contributor aggregation across repos
- Hourly distribution and context switching computation
- Snapshot save/load/compare

The only new code is the **output template** and the **directory-scoped discovery**.

## Key implementation notes from my custom skill

- Discovers repos via `ls -d /*/.git`
- Detects default branch per repo (`origin/main` vs `origin/master`)
- Uses full paths for shell utils (`/usr/bin/grep`, `/usr/bin/awk`) — bare names fail in Claude Code's sandbox eval context
- Avoids `IFS='|' read` in for loops (breaks in the sandbox)
- Saves snapshots to `.context/team-retros/` for week-over-week comparison
- Skips repos with 0 commits in the window silently
- For ~15 repos, the full data gather takes ~30-60s with parallel fetches

Happy to share the full standalone skill implementation if helpful.

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.