mirror of
https://github.com/garrytan/gstack.git
synced 2026-09-09 06:28:59 +02:00
feat(retro): absorb inline git/awk metrics into bin/gstack-retro-metrics + carve report format
RETRO_METRICS_PROTO: 1 contract, local git reads only (fetch stays in the skill prose), degraded path documented in the skeleton. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
co-authored by
Claude Fable 5
Claude Fable 5
parent
b007814be0
commit
e0250aa128
+95
-307
@@ -468,11 +468,20 @@ When the user types `/retro`, run this skill.
|
||||
|
||||
|
||||
|
||||
## Section index — Read each section when its situation applies
|
||||
|
||||
This skill is a decision-tree skeleton. The steps below point to on-demand
|
||||
sections. Read a section in full before doing its step; do not work from memory.
|
||||
|
||||
| When | Read this section |
|
||||
|------|-------------------|
|
||||
| writing the retrospective narrative (Step 14, after all metrics are computed and compared) | `sections/report-format.md` |
|
||||
|
||||
## Instructions
|
||||
|
||||
Parse the argument to determine the time window. Default to 7 days if no argument given. All times should be reported in the user's **local timezone** (use the system default — do NOT set `TZ`).
|
||||
|
||||
**Midnight-aligned windows:** For day (`d`) and week (`w`) units, compute an absolute start date at local midnight, not a relative string. For example, if today is 2026-03-18 and the window is 7 days: the start date is 2026-03-11. Use `--since="2026-03-11T00:00:00"` for git log queries — the explicit `T00:00:00` suffix ensures git starts from midnight. Without it, git uses the current wall-clock time (e.g., `--since="2026-03-11"` at 11pm means 11pm, not midnight). For week units, multiply by 7 to get days (e.g., `2w` = 14 days back). For hour (`h`) units, use `--since="N hours ago"` since midnight alignment does not apply to sub-day windows.
|
||||
**Midnight-aligned windows:** For day (`d`) and week (`w`) units, compute an absolute start date at local midnight, not a relative string. For example, if today is 2026-03-18 and the window is 7 days: the start date is 2026-03-11. Use `--since "2026-03-11T00:00:00"` — the explicit `T00:00:00` suffix ensures git starts from midnight. Without it, git uses the current wall-clock time (e.g., `--since "2026-03-11"` at 11pm means 11pm, not midnight). For week units, multiply by 7 to get days (e.g., `2w` = 14 days back). For hour (`h`) units, use `--since "N hours ago"` since midnight alignment does not apply to sub-day windows. Compute "today" from the user-visible `## currentDate` tag in the session reminder — NEVER from `date` (the system clock can be hours off in containerized harnesses). If you cannot reliably compute "today", stop and ask the user via AskUserQuestion rather than proceeding.
|
||||
|
||||
**Argument validation:** If the argument doesn't match a number followed by `d`, `h`, or `w`, the word `compare` (optionally followed by a window), or the word `global` (optionally followed by a window), show this usage and stop:
|
||||
```
|
||||
@@ -527,142 +536,89 @@ matches a past learning, display:
|
||||
This makes the compounding visible. The user should see that gstack is getting
|
||||
smarter on their codebase over time.
|
||||
|
||||
### Non-git context (optional)
|
||||
### Step 0.5: Freshness pre-flight (fetch)
|
||||
|
||||
Check for non-git context that should be included in the retro:
|
||||
Refresh `origin/<default>` so the retro doesn't misreport against a stale local ref. If the repo has no `origin` remote this fails harmlessly — the metrics script (Step 1) falls back to the local branch and its guard lines disclose it:
|
||||
|
||||
```bash
|
||||
[ -f ~/.gstack/retro-context.md ] && echo "RETRO_CONTEXT_FOUND" || echo "NO_RETRO_CONTEXT"
|
||||
git fetch origin <default> --quiet 2>/dev/null \
|
||||
|| echo "RETRO_FETCH: failed (offline or no remote) — proceeding against last-known refs"
|
||||
```
|
||||
|
||||
If `RETRO_CONTEXT_FOUND`: read `~/.gstack/retro-context.md`. This file is user-authored and may contain meeting notes, calendar events, decisions, and other context that doesn't appear in git history. Incorporate this context into the retro narrative where relevant.
|
||||
Remember whether the fetch succeeded — the stale-base guard in Step 1 only BLOCKs when it did.
|
||||
|
||||
### Step 0.5: Stale-base + bad-today-anchor pre-flight guard
|
||||
### Step 1: Gather Metrics (one command)
|
||||
|
||||
The retro skill computes a window from "today" and queries `git log --since=<window> origin/<default>`. If "today" drifts (model session-context error) or the local worktree's `origin/<default>` is materially behind the actual remote, the window can return zero or near-zero commits and the retro will fabricate a coherent-looking narrative from nothing. This guard prevents silent confidently-wrong output.
|
||||
|
||||
Run the pre-flight in this exact order. The first branch that matches wins:
|
||||
All raw data gathering and metric computation runs through `gstack-retro-metrics` — one command instead of a dozen git pipelines. Substitute the base branch detected in Step 0 and the midnight-aligned start computed above:
|
||||
|
||||
```bash
|
||||
# Pre-check A: no remote configured?
|
||||
_RETRO_HAS_REMOTE=$(git remote 2>/dev/null | grep -c '^origin$' || echo 0)
|
||||
if [ "$_RETRO_HAS_REMOTE" = "0" ]; then
|
||||
echo "RETRO_GUARD: no 'origin' remote, base freshness not verified — proceeding"
|
||||
_RETRO_GUARD_VERDICT="skip-no-remote"
|
||||
fi
|
||||
|
||||
# Pre-check B: detached HEAD or no current base?
|
||||
if [ -z "$_RETRO_GUARD_VERDICT" ]; then
|
||||
_RETRO_HEAD_REF=$(git symbolic-ref --quiet HEAD 2>/dev/null || echo "")
|
||||
if [ -z "$_RETRO_HEAD_REF" ]; then
|
||||
echo "RETRO_GUARD: detached HEAD, base freshness not verified — proceeding"
|
||||
_RETRO_GUARD_VERDICT="skip-detached"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Pre-check C: fetch origin <default>; if it fails, warn but proceed.
|
||||
if [ -z "$_RETRO_GUARD_VERDICT" ]; then
|
||||
if ! git fetch origin <default> --quiet 2>/dev/null; then
|
||||
echo "RETRO_GUARD: 'git fetch origin <default>' failed (offline?) — proceeding against last-known origin/<default>"
|
||||
_RETRO_GUARD_VERDICT="warn-fetch-failed"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Pre-check D: BLOCK only when fetch succeeded AND the latest origin/<default>
|
||||
# commit predates the retro window. Today's date should be loaded from the
|
||||
# user-visible "## currentDate" tag in the session reminder; if the gap between
|
||||
# origin/<default>'s newest commit and today exceeds the window, the model's
|
||||
# "today" is almost certainly stale (or the worktree is wildly behind).
|
||||
if [ -z "$_RETRO_GUARD_VERDICT" ]; then
|
||||
_RETRO_LATEST_ISO=$(git log -1 --format=%ci origin/<default> 2>/dev/null | awk '{print $1}')
|
||||
if [ -n "$_RETRO_LATEST_ISO" ]; then
|
||||
# The model computes today from the session reminder (NEVER from `date` —
|
||||
# the system clock can be hours off in containerized harnesses).
|
||||
# Compute window in DAYS (default 7): if today - latest-commit-date > window-days,
|
||||
# BLOCK. If the model cannot reliably compute "today", it MUST stop here and
|
||||
# ask the user via AskUserQuestion rather than proceeding.
|
||||
echo "RETRO_GUARD: latest origin/<default> commit on $_RETRO_LATEST_ISO"
|
||||
_RETRO_GUARD_VERDICT="check-gap"
|
||||
fi
|
||||
fi
|
||||
_RM="$HOME/.claude/skills/gstack/bin/gstack-retro-metrics"
|
||||
[ -x "$_RM" ] || _RM=".claude/skills/gstack/bin/gstack-retro-metrics"
|
||||
"$_RM" --base "<default>" --since "<since>" \
|
||||
|| echo "RETRO_METRICS: unavailable — stale install (compute metrics manually from the steps below)"
|
||||
```
|
||||
|
||||
After running the bash block, the model evaluates `RETRO_GUARD: latest origin/<default> commit on <DATE>` against today and the window:
|
||||
Read the labeled `METRIC_NAME: value` lines — they feed every step below. **Degraded mode:** if `RETRO_METRICS_PROTO: 1` is missing from the output, the install is stale; compute each metric manually with git commands, using the metric definitions in Steps 2-11 as the spec.
|
||||
|
||||
- If the **latest-commit date is older than (today − window-days)**, BLOCK with: "Retro window is stale. Latest commit on `origin/<default>` was `<DATE>`, but the window covers `<since>` to `<today>`. This usually means either (a) today's date is wrong in this session or (b) `origin/<default>` is materially behind the remote. Confirm today's date via the session reminder; if today is correct, run `git fetch origin <default>` manually and re-run /retro." Stop the skill until the user resolves.
|
||||
- Otherwise, write: "RETRO_GUARD: latest commit `<DATE>` within window — proceeding."
|
||||
**Identity:** `USER_NAME` is **"you"** — the person reading this retro. All other authors are teammates. Orient the narrative around this: "your" commits vs teammate contributions.
|
||||
|
||||
Skip paths (`skip-no-remote`, `skip-detached`, `warn-fetch-failed`) all proceed to Step 1 with the cited reason on a single stderr line so the retro narrative carries the disclosure ("offline run, window not freshness-verified") rather than silently misreporting.
|
||||
**Stale-base + bad-today-anchor guard.** The script echoes `GUARD_LATEST_COMMIT: <DATE>` (newest commit on the analyzed ref). If "today" drifts (model session-context error) or the local `origin/<default>` is materially behind the remote, the window returns zero or near-zero commits and the retro would fabricate a coherent-looking narrative from nothing. Evaluate in this order:
|
||||
|
||||
### Step 1: Gather Raw Data
|
||||
1. If `GUARD_REMOTE: none` or `GUARD_HEAD: detached` or the Step 0.5 fetch failed: proceed, but carry the disclosure into the narrative ("offline run, window not freshness-verified") rather than silently misreporting.
|
||||
2. If the Step 0.5 fetch succeeded AND the `GUARD_LATEST_COMMIT` date is **older than (today − window-days)**: BLOCK with: "Retro window is stale. Latest commit on `origin/<default>` was `<DATE>`, but the window covers `<since>` to `<today>`. This usually means either (a) today's date is wrong in this session or (b) `origin/<default>` is materially behind the remote. Confirm today's date via the session reminder; if today is correct, run `git fetch origin <default>` manually and re-run /retro." Stop the skill until the user resolves.
|
||||
3. Otherwise, write: "RETRO_GUARD: latest commit `<DATE>` within window — proceeding."
|
||||
|
||||
First, fetch origin and identify the current user:
|
||||
```bash
|
||||
git fetch origin <default> --quiet
|
||||
# Identify who is running the retro
|
||||
git config user.name
|
||||
git config user.email
|
||||
```
|
||||
Also check `RETRO_REF`: if it is not `origin/<default>` (local-only repo, missing remote branch), disclose which ref the retro analyzed.
|
||||
|
||||
The name returned by `git config user.name` is **"you"** — the person reading this retro. All other authors are teammates. Use this to orient the narrative: "your" commits vs teammate contributions.
|
||||
**Metric line reference** (what the script emits):
|
||||
|
||||
Run ALL of these git commands in parallel (they are independent):
|
||||
| Line | Meaning |
|
||||
|------|---------|
|
||||
| `COMMIT: hash\|author\|datetime\|+ins/-del\|subject` | One per commit, newest first (capped at 300) — the raw material for narrative anchoring |
|
||||
| `COMMITS` / `MERGE_COMMITS` / `CONTRIBUTORS` | Window totals on the analyzed ref |
|
||||
| `INSERTIONS` / `DELETIONS` / `NET_LOC` | Raw LOC |
|
||||
| `LOGICAL_SLOC_ADDED` | Non-blank, non-comment added lines — the primary code-volume metric |
|
||||
| `TEST_INSERTIONS` / `TEST_RATIO` | Test LOC (test/spec paths + .test./.spec. suffixes) and its share of insertions |
|
||||
| `WEIGHTED_COMMITS` | Commits × files-touched, capped at 20 per commit |
|
||||
| `ACTIVE_DAYS` | Distinct local dates with commits |
|
||||
| `SESSIONS` / `DEEP_SESSIONS` / `MEDIUM_SESSIONS` / `MICRO_SESSIONS` | 45-minute-gap session detection: deep 50+ min, medium 20-50, micro <20 |
|
||||
| `TOTAL_ACTIVE_MINUTES` / `AVG_SESSION_MINUTES` / `LOC_PER_SESSION_HOUR` | Session time aggregates (LOC/hour pre-rounded to nearest 50) |
|
||||
| `COMMIT_TYPES` / `FIX_RATIO` | Conventional-commit prefix mix |
|
||||
| `COMMIT_SIZE_BUCKETS` | small <100 / medium 100-500 / large 500-1500 / xl 1500+ LOC per commit |
|
||||
| `HOURS` / `PEAK_HOUR` | Hourly commit histogram (local time), nonzero hours only |
|
||||
| `FOCUS_SCORE` | % of file changes in the single busiest top-level directory |
|
||||
| `BIGGEST_COMMIT` | Highest-LOC commit in the window (ship-of-the-week candidate) |
|
||||
| `HOTSPOT: count file` | Top 10 most-changed files |
|
||||
| `AUTHOR: name\|commits\|ins\|del\|test_ratio\|top_areas\|types\|peak_hour` | Per-contributor rollup, sorted by commits desc |
|
||||
| `AUTHOR_BIGGEST: name\|hash\|loc\|subject` | Each contributor's biggest ship |
|
||||
| `COAUTHOR: hash\|name` / `AI_ASSISTED_COMMITS` | Human co-author credit lines; count of commits with AI trailers |
|
||||
| `WEEK: wN\|commits\|ins\|del\|test_ratio` | Weekly buckets, w0 = newest (for Step 10 trends) |
|
||||
| `PR_REFS` / `PRS_REFERENCED` | PR/MR numbers from commit subjects (GitHub #NNN, GitLab !NNN) |
|
||||
| `TEST_FILES_TOTAL` / `TEST_FILES_CHANGED` / `REGRESSION_TEST_COMMITS` / `REGRESSION_COMMIT` | Test health: repo-wide test file count, test files changed in window, `test(qa):` / `test(design):` / `test: coverage` commits |
|
||||
| `VERSION_RANGE` | First → last VERSION file value in the window (when tracked) |
|
||||
| `TEAM_STREAK` / `USER_STREAK` | Consecutive commit days with anchor date (Step 11) |
|
||||
| `RETRO_CONTEXT` / `GREPTILE_HISTORY` / `TODOS_FILE` / `SKILL_USAGE_LOG` / `EUREKA_LOG` | Presence of optional inputs — Read the ones marked present |
|
||||
|
||||
```bash
|
||||
# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
|
||||
git log origin/<default> --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat
|
||||
**Optional inputs** (Read each file the script marks `present`):
|
||||
|
||||
# 2. Per-commit test vs total LOC breakdown with author
|
||||
# Each commit block starts with COMMIT:<hash>|<author>, followed by numstat lines.
|
||||
# Separate test files (matching test/|spec/|__tests__/) from production files.
|
||||
git log origin/<default> --since="<window>" --format="COMMIT:%H|%aN" --numstat
|
||||
|
||||
# 3. Commit timestamps for session detection and hourly distribution (with author)
|
||||
git log origin/<default> --since="<window>" --format="%at|%aN|%ai|%s" | sort -n
|
||||
|
||||
# 4. Files most frequently changed (hotspot analysis)
|
||||
git log origin/<default> --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn
|
||||
|
||||
# 5. PR/MR numbers from commit messages (GitHub #NNN, GitLab !NNN)
|
||||
git log origin/<default> --since="<window>" --format="%s" | grep -oE '[#!][0-9]+' | sort -t'#' -k1 | uniq
|
||||
|
||||
# 6. Per-author file hotspots (who touches what)
|
||||
git log origin/<default> --since="<window>" --format="AUTHOR:%aN" --name-only
|
||||
|
||||
# 7. Per-author commit counts (quick summary)
|
||||
git shortlog origin/<default> --since="<window>" -sn --no-merges
|
||||
|
||||
# 8. Greptile triage history (if available)
|
||||
cat ~/.gstack/greptile-history.md 2>/dev/null || true
|
||||
|
||||
# 9. TODOS.md backlog (if available)
|
||||
cat TODOS.md 2>/dev/null || true
|
||||
|
||||
# 10. Test file count
|
||||
git ls-files 2>/dev/null | grep -E '(\.test\.|\.spec\.|_test\.|_spec\.)' | wc -l
|
||||
|
||||
# 11. Regression test commits in window
|
||||
git log origin/<default> --since="<window>" --oneline --grep="test(qa):" --grep="test(design):" --grep="test: coverage"
|
||||
|
||||
# 12. gstack skill usage telemetry (if available)
|
||||
cat ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
|
||||
# 12. Test files changed in window
|
||||
git log origin/<default> --since="<window>" --format="" --name-only | grep -E '\.(test|spec)\.' | sort -u | wc -l
|
||||
```
|
||||
- `RETRO_CONTEXT: present` → Read `~/.gstack/retro-context.md`. It is user-authored and may contain meeting notes, calendar events, decisions, and other context that doesn't appear in git history. Incorporate it into the retro narrative where relevant.
|
||||
- `GREPTILE_HISTORY: present` → Read `~/.gstack/greptile-history.md`. Filter entries to the retro window by date. Count by type: `fix`, `fp`, `already-fixed`. Signal ratio = `(fix + already-fixed) / (fix + already-fixed + fp)`. Skip unparseable lines silently; if no entries fall in the window, skip the Greptile metric row.
|
||||
- `TODOS_FILE: present` → Read `TODOS.md`. Compute: total open TODOs (exclude the `## Completed` section), P0/P1 count, P2 count, items completed this period (Completed entries dated within the window), items added this period (cross-reference `COMMIT:` lines that touched TODOS.md).
|
||||
- `SKILL_USAGE_LOG: present` → Read `~/.gstack/analytics/skill-usage.jsonl`. Filter to the window by `ts`. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name.
|
||||
- `EUREKA_LOG: present` → Read `~/.gstack/analytics/eureka.jsonl`. Filter to the window by `ts`. For each eureka moment note the skill that flagged it, the branch, and a one-line summary of the insight.
|
||||
|
||||
### Step 2: Compute Metrics
|
||||
|
||||
Calculate and present these metrics in a summary table:
|
||||
Present these metrics in a summary table, straight from the metric lines:
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| **Features shipped** (from CHANGELOG + merged PR titles) | N |
|
||||
| Commits to main | N |
|
||||
| Weighted commits (commits × avg files-touched, capped at 20 per commit) | N |
|
||||
| Weighted commits (`WEIGHTED_COMMITS`) | N |
|
||||
| Contributors | N |
|
||||
| PRs merged | N |
|
||||
| **Logical SLOC added** (non-blank, non-comment — primary code-volume metric) | N |
|
||||
| **Logical SLOC added** (`LOGICAL_SLOC_ADDED` — primary code-volume metric) | N |
|
||||
| Raw LOC: insertions | N |
|
||||
| Raw LOC: deletions | N |
|
||||
| Raw LOC: net | N |
|
||||
@@ -681,7 +637,7 @@ new functionality. Raw LOC is demoted to context because AI inflates it; ten
|
||||
lines of a good fix is not less shipping than ten thousand lines of scaffold.
|
||||
See docs/designs/PLAN_TUNING_V1.md §Workstream C.
|
||||
|
||||
Then show a **per-author leaderboard** immediately below:
|
||||
Then show a **per-author leaderboard** immediately below, from the `AUTHOR:` lines:
|
||||
|
||||
```
|
||||
Contributor Commits +/- Top area
|
||||
@@ -690,49 +646,25 @@ alice 12 +800/-150 app/services/
|
||||
bob 3 +120/-40 tests/
|
||||
```
|
||||
|
||||
Sort by commits descending. The current user (from `git config user.name`) always appears first, labeled "You (name)".
|
||||
Sort by commits descending. The current user (`USER_NAME`) always appears first, labeled "You (name)".
|
||||
|
||||
**Greptile signal (if history exists):** Read `~/.gstack/greptile-history.md` (fetched in Step 1, command 8). Filter entries within the retro time window by date. Count entries by type: `fix`, `fp`, `already-fixed`. Compute signal ratio: `(fix + already-fixed) / (fix + already-fixed + fp)`. If no entries exist in the window or the file doesn't exist, skip the Greptile metric row. Skip unparseable lines silently.
|
||||
Conditional rows (skip each when its input is absent or empty in the window):
|
||||
|
||||
**Backlog Health (if TODOS.md exists):** Read `TODOS.md` (fetched in Step 1, command 9). Compute:
|
||||
- Total open TODOs (exclude items in `## Completed` section)
|
||||
- P0/P1 count (critical/urgent items)
|
||||
- P2 count (important items)
|
||||
- Items completed this period (items in Completed section with dates within the retro window)
|
||||
- Items added this period (cross-reference git log for commits that modified TODOS.md within the window)
|
||||
|
||||
Include in the metrics table:
|
||||
```
|
||||
| Backlog Health | N open (X P0/P1, Y P2) · Z completed this period |
|
||||
```
|
||||
|
||||
If TODOS.md doesn't exist, skip the Backlog Health row.
|
||||
|
||||
**Skill Usage (if analytics exist):** Read `~/.gstack/analytics/skill-usage.jsonl` if it exists. Filter entries within the retro time window by `ts` field. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name. Present as:
|
||||
|
||||
```
|
||||
| Skill Usage | /ship(12) /qa(8) /review(5) · 3 safety hook fires |
|
||||
```
|
||||
|
||||
If the JSONL file doesn't exist or has no entries in the window, skip the Skill Usage row.
|
||||
|
||||
**Eureka Moments (if logged):** Read `~/.gstack/analytics/eureka.jsonl` if it exists. Filter entries within the retro time window by `ts` field. For each eureka moment, show the skill that flagged it, the branch, and a one-line summary of the insight. Present as:
|
||||
|
||||
```
|
||||
| Eureka Moments | 2 this period |
|
||||
```
|
||||
|
||||
If moments exist, list them:
|
||||
If eureka moments exist, list them:
|
||||
```
|
||||
EUREKA /office-hours (branch: garrytan/auth-rethink): "Session tokens don't need server storage — browser crypto API makes client-side JWT validation viable"
|
||||
EUREKA /plan-eng-review (branch: garrytan/cache-layer): "Redis isn't needed here — Bun's built-in LRU cache handles this workload"
|
||||
```
|
||||
|
||||
If the JSONL file doesn't exist or has no entries in the window, skip the Eureka Moments row.
|
||||
|
||||
### Step 3: Commit Time Distribution
|
||||
|
||||
Show hourly histogram in local time using bar chart:
|
||||
Render the `HOURS` line as an hourly histogram in local time:
|
||||
|
||||
```
|
||||
Hour Commits ████████████████
|
||||
@@ -749,24 +681,14 @@ Identify and call out:
|
||||
|
||||
### Step 4: Work Session Detection
|
||||
|
||||
Detect sessions using **45-minute gap** threshold between consecutive commits. For each session report:
|
||||
- Start/end time (Pacific)
|
||||
- Number of commits
|
||||
- Duration in minutes
|
||||
|
||||
Classify sessions:
|
||||
- **Deep sessions** (50+ min)
|
||||
- **Medium sessions** (20-50 min)
|
||||
- **Micro sessions** (<20 min, typically single-commit fire-and-forget)
|
||||
|
||||
Calculate:
|
||||
- Total active coding time (sum of session durations)
|
||||
- Average session length
|
||||
- LOC per hour of active time
|
||||
Sessions are pre-computed with a **45-minute gap** threshold between consecutive commits (`SESSIONS`, `DEEP_SESSIONS` 50+ min, `MEDIUM_SESSIONS` 20-50 min, `MICRO_SESSIONS` <20 min — typically single-commit fire-and-forget). Report:
|
||||
- Session count and the deep/medium/micro split
|
||||
- Total active coding time (`TOTAL_ACTIVE_MINUTES`) and average session length
|
||||
- LOC per hour of active time (`LOC_PER_SESSION_HOUR`)
|
||||
|
||||
### Step 5: Commit Type Breakdown
|
||||
|
||||
Categorize by conventional commit prefix (feat/fix/refactor/test/chore/docs). Show as percentage bar:
|
||||
Render `COMMIT_TYPES` (feat/fix/refactor/test/chore/docs) as a percentage bar:
|
||||
|
||||
```
|
||||
feat: 20 (40%) ████████████████████
|
||||
@@ -774,18 +696,18 @@ fix: 27 (54%) ███████████████████
|
||||
refactor: 2 ( 4%) ██
|
||||
```
|
||||
|
||||
Flag if fix ratio exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
|
||||
Flag if `FIX_RATIO` exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
|
||||
|
||||
### Step 6: Hotspot Analysis
|
||||
|
||||
Show top 10 most-changed files. Flag:
|
||||
Show the `HOTSPOT` lines (top 10 most-changed files). Flag:
|
||||
- Files changed 5+ times (churn hotspots)
|
||||
- Test files vs production files in the hotspot list
|
||||
- VERSION/CHANGELOG frequency (version discipline indicator)
|
||||
|
||||
### Step 7: PR Size Distribution
|
||||
|
||||
From commit diffs, estimate PR sizes and bucket them:
|
||||
Report `COMMIT_SIZE_BUCKETS`:
|
||||
- **Small** (<100 LOC)
|
||||
- **Medium** (100-500 LOC)
|
||||
- **Large** (500-1500 LOC)
|
||||
@@ -793,23 +715,16 @@ From commit diffs, estimate PR sizes and bucket them:
|
||||
|
||||
### Step 8: Focus Score + Ship of the Week
|
||||
|
||||
**Focus score:** Calculate the percentage of commits touching the single most-changed top-level directory (e.g., `app/services/`, `app/views/`). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
|
||||
**Focus score:** `FOCUS_SCORE` is the percentage of file changes touching the single most-changed top-level directory (e.g., `app/services/`). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
|
||||
|
||||
**Ship of the week:** Auto-identify the single highest-LOC PR in the window. Highlight it:
|
||||
- PR number and title
|
||||
**Ship of the week:** `BIGGEST_COMMIT` is the highest-LOC change in the window. Highlight it:
|
||||
- PR number (match against `PR_REFS` / the subject) and title
|
||||
- LOC changed
|
||||
- Why it matters (infer from commit messages and files touched)
|
||||
|
||||
### Step 9: Team Member Analysis
|
||||
|
||||
For each contributor (including the current user), compute:
|
||||
|
||||
1. **Commits and LOC** — total commits, insertions, deletions, net LOC
|
||||
2. **Areas of focus** — which directories/files they touched most (top 3)
|
||||
3. **Commit type mix** — their personal feat/fix/refactor/test breakdown
|
||||
4. **Session patterns** — when they code (their peak hours), session count
|
||||
5. **Test discipline** — their personal test LOC ratio
|
||||
6. **Biggest ship** — their single highest-impact commit or PR in the window
|
||||
For each contributor (including the current user), the `AUTHOR:` line carries commits, insertions, deletions, test ratio, top areas, commit type mix, and peak hour; `AUTHOR_BIGGEST:` carries their single highest-impact commit. Use the `COMMIT:` lines to anchor everything in actual work.
|
||||
|
||||
**For the current user ("You"):** This section gets the deepest treatment. Include all the detail from the solo retro — session analysis, time patterns, focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."
|
||||
|
||||
@@ -820,7 +735,7 @@ For each contributor (including the current user), compute:
|
||||
|
||||
**If only one contributor (solo repo):** Skip the team breakdown and proceed as before — the retro is personal.
|
||||
|
||||
**If there are Co-Authored-By trailers:** Parse `Co-Authored-By:` lines in commit messages. Credit those authors for the commit alongside the primary author. Note AI co-authors (e.g., `noreply@anthropic.com`) but do not include them as team members — instead, track "AI-assisted commits" as a separate metric.
|
||||
**Co-author credit:** `COAUTHOR:` lines carry human `Co-Authored-By:` trailers — credit those authors for the commit alongside the primary author. AI co-authors (e.g., `noreply@anthropic.com`) are counted in `AI_ASSISTED_COMMITS` instead — track "AI-assisted commits" as a separate metric, never as a team member.
|
||||
|
||||
## Capture Learnings
|
||||
|
||||
@@ -851,28 +766,17 @@ already knows. A good test: would this insight save time in a future session? If
|
||||
|
||||
### Step 10: Week-over-Week Trends (if window >= 14d)
|
||||
|
||||
If the time window is 14 days or more, split into weekly buckets and show trends:
|
||||
- Commits per week (total and per-author)
|
||||
If the time window is 14 days or more, use the `WEEK:` lines (w0 = the week containing the newest commit) to show trends:
|
||||
- Commits per week (total; per-author from the `COMMIT:` lines)
|
||||
- LOC per week
|
||||
- Test ratio per week
|
||||
- Fix ratio per week
|
||||
- Session count per week
|
||||
|
||||
### Step 11: Streak Tracking
|
||||
|
||||
Count consecutive days with at least 1 commit to origin/<default>, going back from today. Track both team streak and personal streak:
|
||||
|
||||
```bash
|
||||
# Team streak: all unique commit dates (local time) — no hard cutoff
|
||||
git log origin/<default> --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
|
||||
# Personal streak: only the current user's commits
|
||||
git log origin/<default> --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
```
|
||||
|
||||
Count backward from today — how many consecutive days have at least one commit? This queries the full history so streaks of any length are reported accurately. Display both:
|
||||
- "Team shipping streak: 47 consecutive days"
|
||||
- "Your shipping streak: 32 consecutive days"
|
||||
`TEAM_STREAK` and `USER_STREAK` count consecutive days with at least 1 commit (full history, no cutoff), anchored at the **newest commit date** — not at today, because the script never trusts the system clock. Interpret against today from the session reminder:
|
||||
- If the anchor date is today or yesterday, the streak is live: "Team shipping streak: 47 consecutive days" / "Your shipping streak: 32 consecutive days"
|
||||
- If the anchor is older, the streak is broken: report 0 days and note the last shipping day.
|
||||
|
||||
### Step 12: Load History & Compare
|
||||
|
||||
@@ -954,7 +858,7 @@ Use the Write tool to save the JSON file with this schema:
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Only include the `greptile` field if `~/.gstack/greptile-history.md` exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (command 10 returns > 0). If any has no data, omit the field entirely.
|
||||
**Note:** Only include the `greptile` field if `~/.gstack/greptile-history.md` exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (`TEST_FILES_TOTAL` > 0). If any has no data, omit the field entirely.
|
||||
|
||||
Include test health data in the JSON when test files exist:
|
||||
```json
|
||||
@@ -979,124 +883,8 @@ Include backlog data in the JSON when TODOS.md exists:
|
||||
|
||||
### Step 14: Write the Narrative
|
||||
|
||||
Structure the output as:
|
||||
|
||||
---
|
||||
|
||||
**Tweetable summary** (first line, before everything else):
|
||||
```
|
||||
Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
|
||||
```
|
||||
|
||||
## Engineering Retro: [date range]
|
||||
|
||||
### Summary Table
|
||||
(from Step 2)
|
||||
|
||||
### Trends vs Last Retro
|
||||
(from Step 11, loaded before save — skip if first retro)
|
||||
|
||||
### Time & Session Patterns
|
||||
(from Steps 3-4)
|
||||
|
||||
Narrative interpreting what the team-wide patterns mean:
|
||||
- When the most productive hours are and what drives them
|
||||
- Whether sessions are getting longer or shorter over time
|
||||
- Estimated hours per day of active coding (team aggregate)
|
||||
- Notable patterns: do team members code at the same time or in shifts?
|
||||
|
||||
### Shipping Velocity
|
||||
(from Steps 5-7)
|
||||
|
||||
Narrative covering:
|
||||
- Commit type mix and what it reveals
|
||||
- PR size distribution and what it reveals about shipping cadence
|
||||
- Fix-chain detection (sequences of fix commits on the same subsystem)
|
||||
- Version bump discipline
|
||||
|
||||
### Code Quality Signals
|
||||
- Test LOC ratio trend
|
||||
- Hotspot analysis (are the same files churning?)
|
||||
- Greptile signal ratio and trend (if history exists): "Greptile: X% signal (Y valid catches, Z false positives)"
|
||||
|
||||
### Test Health
|
||||
- Total test files: N (from command 10)
|
||||
- Tests added this period: M (from command 12 — test files changed)
|
||||
- Regression test commits: list `test(qa):` and `test(design):` and `test: coverage` commits from command 11
|
||||
- If prior retro exists and has `test_health`: show delta "Test count: {last} → {now} (+{delta})"
|
||||
- If test ratio < 20%: flag as growth area — "100% test coverage is the goal. Tests make vibe coding safe."
|
||||
|
||||
### Plan Completion
|
||||
Check review JSONL logs for plan completion data from /ship runs this period:
|
||||
|
||||
```bash
|
||||
setopt +o nomatch 2>/dev/null || true # zsh compat
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
cat ~/.gstack/projects/$SLUG/*-reviews.jsonl 2>/dev/null | grep '"skill":"ship"' | grep '"plan_items_total"' || echo "NO_PLAN_DATA"
|
||||
```
|
||||
|
||||
If plan completion data exists within the retro time window:
|
||||
- Count branches shipped with plans (entries that have `plan_items_total` > 0)
|
||||
- Compute average completion: sum of `plan_items_done` / sum of `plan_items_total`
|
||||
- Identify most-skipped item category if data supports it
|
||||
|
||||
Output:
|
||||
```
|
||||
Plan Completion This Period:
|
||||
{N} branches shipped with plans
|
||||
Average completion: {X}% ({done}/{total} items)
|
||||
```
|
||||
|
||||
If no plan data exists, skip this section silently.
|
||||
|
||||
### Focus & Highlights
|
||||
(from Step 8)
|
||||
- Focus score with interpretation
|
||||
- Ship of the week callout
|
||||
|
||||
### Your Week (personal deep-dive)
|
||||
(from Step 9, for the current user only)
|
||||
|
||||
This is the section the user cares most about. Include:
|
||||
- Their personal commit count, LOC, test ratio
|
||||
- Their session patterns and peak hours
|
||||
- Their focus areas
|
||||
- Their biggest ship
|
||||
- **What you did well** (2-3 specific things anchored in commits)
|
||||
- **Where to level up** (1-2 specific, actionable suggestions)
|
||||
|
||||
### Team Breakdown
|
||||
(from Step 9, for each teammate — skip if solo repo)
|
||||
|
||||
For each teammate (sorted by commits descending), write a section:
|
||||
|
||||
#### [Name]
|
||||
- **What they shipped**: 2-3 sentences on their contributions, areas of focus, and commit patterns
|
||||
- **Praise**: 1-2 specific things they did well, anchored in actual commits. Be genuine — what would you actually say in a 1:1? Examples:
|
||||
- "Cleaned up the entire auth module in 3 small, reviewable PRs — textbook decomposition"
|
||||
- "Added integration tests for every new endpoint, not just happy paths"
|
||||
- "Fixed the N+1 query that was causing 2s load times on the dashboard"
|
||||
- **Opportunity for growth**: 1 specific, constructive suggestion. Frame as investment, not criticism. Examples:
|
||||
- "Test coverage on the payment module is at 8% — worth investing in before the next feature lands on top of it"
|
||||
- "Most commits land in a single burst — spacing work across the day could reduce context-switching fatigue"
|
||||
- "All commits land between 1-4am — sustainable pace matters for code quality long-term"
|
||||
|
||||
**AI collaboration note:** If many commits have `Co-Authored-By` AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
|
||||
|
||||
### Top 3 Team Wins
|
||||
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
|
||||
- What it was
|
||||
- Who shipped it
|
||||
- Why it matters (product/architecture impact)
|
||||
|
||||
### 3 Things to Improve
|
||||
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
|
||||
|
||||
### 3 Habits for Next Week
|
||||
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
|
||||
|
||||
### Week-over-Week Trends
|
||||
(if applicable, from Step 10)
|
||||
> **STOP.** Before writing the retrospective narrative (Step 14, after all metrics are computed and compared), Read `~/.claude/skills/gstack/retro/sections/report-format.md` and execute it
|
||||
> in full. Do not work from memory — that section is the source of truth for this step.
|
||||
|
||||
---
|
||||
|
||||
@@ -1393,8 +1181,8 @@ Use the Write tool to save JSON to `~/.gstack/retros/global-${today}-${next}.jso
|
||||
|
||||
When the user runs `/retro compare` (or `/retro compare 14d`):
|
||||
|
||||
1. Compute metrics for the current window (default 7d) using the midnight-aligned start date (same logic as the main retro — e.g., if today is 2026-03-18 and window is 7d, use `--since="2026-03-11T00:00:00"`)
|
||||
2. Compute metrics for the immediately prior same-length window using both `--since` and `--until` with midnight-aligned dates to avoid overlap (e.g., for a 7d window starting 2026-03-11: prior window is `--since="2026-03-04T00:00:00" --until="2026-03-11T00:00:00"`)
|
||||
1. Run Steps 0.5-1 for the current window (default 7d) using the midnight-aligned start date (same logic as the main retro — e.g., if today is 2026-03-18 and window is 7d, `--since "2026-03-11T00:00:00"`)
|
||||
2. Run `gstack-retro-metrics` a second time for the immediately prior same-length window, using both `--since` and `--until` with midnight-aligned dates to avoid overlap (e.g., for a 7d window starting 2026-03-11: `--since "2026-03-04T00:00:00" --until "2026-03-11T00:00:00"`)
|
||||
3. Show a side-by-side comparison table with deltas and arrows
|
||||
4. Write a brief narrative highlighting the biggest improvements and regressions
|
||||
5. Save only the current-window snapshot to `.context/retros/` (same as a normal retro run); do **not** persist the prior-window metrics.
|
||||
@@ -1415,10 +1203,10 @@ When the user runs `/retro compare` (or `/retro compare 14d`):
|
||||
## Important Rules
|
||||
|
||||
- ALL narrative output goes directly to the user in the conversation. The ONLY file written is the `.context/retros/` JSON snapshot.
|
||||
- Use `origin/<default>` for all git queries (not local main which may be stale)
|
||||
- The metrics script analyzes `origin/<default>` (not local main which may be stale); when `RETRO_REF` says otherwise, disclose it
|
||||
- Display all timestamps in the user's local timezone (do not override `TZ`)
|
||||
- If the window has zero commits, say so and suggest a different window
|
||||
- Round LOC/hour to nearest 50
|
||||
- If `COMMITS: 0`, say so and suggest a different window
|
||||
- Round LOC/hour to nearest 50 (the script pre-rounds `LOC_PER_SESSION_HOUR`)
|
||||
- Treat merge commits as PR boundaries
|
||||
- Do not read CLAUDE.md or other docs — this skill is self-contained
|
||||
- On first run (no prior retros), skip comparison sections gracefully
|
||||
|
||||
+87
-307
@@ -65,11 +65,13 @@ When the user types `/retro`, run this skill.
|
||||
|
||||
{{GBRAIN_CONTEXT_LOAD}}
|
||||
|
||||
{{SECTION_INDEX:retro}}
|
||||
|
||||
## Instructions
|
||||
|
||||
Parse the argument to determine the time window. Default to 7 days if no argument given. All times should be reported in the user's **local timezone** (use the system default — do NOT set `TZ`).
|
||||
|
||||
**Midnight-aligned windows:** For day (`d`) and week (`w`) units, compute an absolute start date at local midnight, not a relative string. For example, if today is 2026-03-18 and the window is 7 days: the start date is 2026-03-11. Use `--since="2026-03-11T00:00:00"` for git log queries — the explicit `T00:00:00` suffix ensures git starts from midnight. Without it, git uses the current wall-clock time (e.g., `--since="2026-03-11"` at 11pm means 11pm, not midnight). For week units, multiply by 7 to get days (e.g., `2w` = 14 days back). For hour (`h`) units, use `--since="N hours ago"` since midnight alignment does not apply to sub-day windows.
|
||||
**Midnight-aligned windows:** For day (`d`) and week (`w`) units, compute an absolute start date at local midnight, not a relative string. For example, if today is 2026-03-18 and the window is 7 days: the start date is 2026-03-11. Use `--since "2026-03-11T00:00:00"` — the explicit `T00:00:00` suffix ensures git starts from midnight. Without it, git uses the current wall-clock time (e.g., `--since "2026-03-11"` at 11pm means 11pm, not midnight). For week units, multiply by 7 to get days (e.g., `2w` = 14 days back). For hour (`h`) units, use `--since "N hours ago"` since midnight alignment does not apply to sub-day windows. Compute "today" from the user-visible `## currentDate` tag in the session reminder — NEVER from `date` (the system clock can be hours off in containerized harnesses). If you cannot reliably compute "today", stop and ask the user via AskUserQuestion rather than proceeding.
|
||||
|
||||
**Argument validation:** If the argument doesn't match a number followed by `d`, `h`, or `w`, the word `compare` (optionally followed by a window), or the word `global` (optionally followed by a window), show this usage and stop:
|
||||
```
|
||||
@@ -88,142 +90,89 @@ Usage: /retro [window | compare | global]
|
||||
|
||||
{{LEARNINGS_SEARCH}}
|
||||
|
||||
### Non-git context (optional)
|
||||
### Step 0.5: Freshness pre-flight (fetch)
|
||||
|
||||
Check for non-git context that should be included in the retro:
|
||||
Refresh `origin/<default>` so the retro doesn't misreport against a stale local ref. If the repo has no `origin` remote this fails harmlessly — the metrics script (Step 1) falls back to the local branch and its guard lines disclose it:
|
||||
|
||||
```bash
|
||||
[ -f ~/.gstack/retro-context.md ] && echo "RETRO_CONTEXT_FOUND" || echo "NO_RETRO_CONTEXT"
|
||||
git fetch origin <default> --quiet 2>/dev/null \
|
||||
|| echo "RETRO_FETCH: failed (offline or no remote) — proceeding against last-known refs"
|
||||
```
|
||||
|
||||
If `RETRO_CONTEXT_FOUND`: read `~/.gstack/retro-context.md`. This file is user-authored and may contain meeting notes, calendar events, decisions, and other context that doesn't appear in git history. Incorporate this context into the retro narrative where relevant.
|
||||
Remember whether the fetch succeeded — the stale-base guard in Step 1 only BLOCKs when it did.
|
||||
|
||||
### Step 0.5: Stale-base + bad-today-anchor pre-flight guard
|
||||
### Step 1: Gather Metrics (one command)
|
||||
|
||||
The retro skill computes a window from "today" and queries `git log --since=<window> origin/<default>`. If "today" drifts (model session-context error) or the local worktree's `origin/<default>` is materially behind the actual remote, the window can return zero or near-zero commits and the retro will fabricate a coherent-looking narrative from nothing. This guard prevents silent confidently-wrong output.
|
||||
|
||||
Run the pre-flight in this exact order. The first branch that matches wins:
|
||||
All raw data gathering and metric computation runs through `gstack-retro-metrics` — one command instead of a dozen git pipelines. Substitute the base branch detected in Step 0 and the midnight-aligned start computed above:
|
||||
|
||||
```bash
|
||||
# Pre-check A: no remote configured?
|
||||
_RETRO_HAS_REMOTE=$(git remote 2>/dev/null | grep -c '^origin$' || echo 0)
|
||||
if [ "$_RETRO_HAS_REMOTE" = "0" ]; then
|
||||
echo "RETRO_GUARD: no 'origin' remote, base freshness not verified — proceeding"
|
||||
_RETRO_GUARD_VERDICT="skip-no-remote"
|
||||
fi
|
||||
|
||||
# Pre-check B: detached HEAD or no current base?
|
||||
if [ -z "$_RETRO_GUARD_VERDICT" ]; then
|
||||
_RETRO_HEAD_REF=$(git symbolic-ref --quiet HEAD 2>/dev/null || echo "")
|
||||
if [ -z "$_RETRO_HEAD_REF" ]; then
|
||||
echo "RETRO_GUARD: detached HEAD, base freshness not verified — proceeding"
|
||||
_RETRO_GUARD_VERDICT="skip-detached"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Pre-check C: fetch origin <default>; if it fails, warn but proceed.
|
||||
if [ -z "$_RETRO_GUARD_VERDICT" ]; then
|
||||
if ! git fetch origin <default> --quiet 2>/dev/null; then
|
||||
echo "RETRO_GUARD: 'git fetch origin <default>' failed (offline?) — proceeding against last-known origin/<default>"
|
||||
_RETRO_GUARD_VERDICT="warn-fetch-failed"
|
||||
fi
|
||||
fi
|
||||
|
||||
# Pre-check D: BLOCK only when fetch succeeded AND the latest origin/<default>
|
||||
# commit predates the retro window. Today's date should be loaded from the
|
||||
# user-visible "## currentDate" tag in the session reminder; if the gap between
|
||||
# origin/<default>'s newest commit and today exceeds the window, the model's
|
||||
# "today" is almost certainly stale (or the worktree is wildly behind).
|
||||
if [ -z "$_RETRO_GUARD_VERDICT" ]; then
|
||||
_RETRO_LATEST_ISO=$(git log -1 --format=%ci origin/<default> 2>/dev/null | awk '{print $1}')
|
||||
if [ -n "$_RETRO_LATEST_ISO" ]; then
|
||||
# The model computes today from the session reminder (NEVER from `date` —
|
||||
# the system clock can be hours off in containerized harnesses).
|
||||
# Compute window in DAYS (default 7): if today - latest-commit-date > window-days,
|
||||
# BLOCK. If the model cannot reliably compute "today", it MUST stop here and
|
||||
# ask the user via AskUserQuestion rather than proceeding.
|
||||
echo "RETRO_GUARD: latest origin/<default> commit on $_RETRO_LATEST_ISO"
|
||||
_RETRO_GUARD_VERDICT="check-gap"
|
||||
fi
|
||||
fi
|
||||
_RM="$HOME/.claude/skills/gstack/bin/gstack-retro-metrics"
|
||||
[ -x "$_RM" ] || _RM=".claude/skills/gstack/bin/gstack-retro-metrics"
|
||||
"$_RM" --base "<default>" --since "<since>" \
|
||||
|| echo "RETRO_METRICS: unavailable — stale install (compute metrics manually from the steps below)"
|
||||
```
|
||||
|
||||
After running the bash block, the model evaluates `RETRO_GUARD: latest origin/<default> commit on <DATE>` against today and the window:
|
||||
Read the labeled `METRIC_NAME: value` lines — they feed every step below. **Degraded mode:** if `RETRO_METRICS_PROTO: 1` is missing from the output, the install is stale; compute each metric manually with git commands, using the metric definitions in Steps 2-11 as the spec.
|
||||
|
||||
- If the **latest-commit date is older than (today − window-days)**, BLOCK with: "Retro window is stale. Latest commit on `origin/<default>` was `<DATE>`, but the window covers `<since>` to `<today>`. This usually means either (a) today's date is wrong in this session or (b) `origin/<default>` is materially behind the remote. Confirm today's date via the session reminder; if today is correct, run `git fetch origin <default>` manually and re-run /retro." Stop the skill until the user resolves.
|
||||
- Otherwise, write: "RETRO_GUARD: latest commit `<DATE>` within window — proceeding."
|
||||
**Identity:** `USER_NAME` is **"you"** — the person reading this retro. All other authors are teammates. Orient the narrative around this: "your" commits vs teammate contributions.
|
||||
|
||||
Skip paths (`skip-no-remote`, `skip-detached`, `warn-fetch-failed`) all proceed to Step 1 with the cited reason on a single stderr line so the retro narrative carries the disclosure ("offline run, window not freshness-verified") rather than silently misreporting.
|
||||
**Stale-base + bad-today-anchor guard.** The script echoes `GUARD_LATEST_COMMIT: <DATE>` (newest commit on the analyzed ref). If "today" drifts (model session-context error) or the local `origin/<default>` is materially behind the remote, the window returns zero or near-zero commits and the retro would fabricate a coherent-looking narrative from nothing. Evaluate in this order:
|
||||
|
||||
### Step 1: Gather Raw Data
|
||||
1. If `GUARD_REMOTE: none` or `GUARD_HEAD: detached` or the Step 0.5 fetch failed: proceed, but carry the disclosure into the narrative ("offline run, window not freshness-verified") rather than silently misreporting.
|
||||
2. If the Step 0.5 fetch succeeded AND the `GUARD_LATEST_COMMIT` date is **older than (today − window-days)**: BLOCK with: "Retro window is stale. Latest commit on `origin/<default>` was `<DATE>`, but the window covers `<since>` to `<today>`. This usually means either (a) today's date is wrong in this session or (b) `origin/<default>` is materially behind the remote. Confirm today's date via the session reminder; if today is correct, run `git fetch origin <default>` manually and re-run /retro." Stop the skill until the user resolves.
|
||||
3. Otherwise, write: "RETRO_GUARD: latest commit `<DATE>` within window — proceeding."
|
||||
|
||||
First, fetch origin and identify the current user:
|
||||
```bash
|
||||
git fetch origin <default> --quiet
|
||||
# Identify who is running the retro
|
||||
git config user.name
|
||||
git config user.email
|
||||
```
|
||||
Also check `RETRO_REF`: if it is not `origin/<default>` (local-only repo, missing remote branch), disclose which ref the retro analyzed.
|
||||
|
||||
The name returned by `git config user.name` is **"you"** — the person reading this retro. All other authors are teammates. Use this to orient the narrative: "your" commits vs teammate contributions.
|
||||
**Metric line reference** (what the script emits):
|
||||
|
||||
Run ALL of these git commands in parallel (they are independent):
|
||||
| Line | Meaning |
|
||||
|------|---------|
|
||||
| `COMMIT: hash\|author\|datetime\|+ins/-del\|subject` | One per commit, newest first (capped at 300) — the raw material for narrative anchoring |
|
||||
| `COMMITS` / `MERGE_COMMITS` / `CONTRIBUTORS` | Window totals on the analyzed ref |
|
||||
| `INSERTIONS` / `DELETIONS` / `NET_LOC` | Raw LOC |
|
||||
| `LOGICAL_SLOC_ADDED` | Non-blank, non-comment added lines — the primary code-volume metric |
|
||||
| `TEST_INSERTIONS` / `TEST_RATIO` | Test LOC (test/spec paths + .test./.spec. suffixes) and its share of insertions |
|
||||
| `WEIGHTED_COMMITS` | Commits × files-touched, capped at 20 per commit |
|
||||
| `ACTIVE_DAYS` | Distinct local dates with commits |
|
||||
| `SESSIONS` / `DEEP_SESSIONS` / `MEDIUM_SESSIONS` / `MICRO_SESSIONS` | 45-minute-gap session detection: deep 50+ min, medium 20-50, micro <20 |
|
||||
| `TOTAL_ACTIVE_MINUTES` / `AVG_SESSION_MINUTES` / `LOC_PER_SESSION_HOUR` | Session time aggregates (LOC/hour pre-rounded to nearest 50) |
|
||||
| `COMMIT_TYPES` / `FIX_RATIO` | Conventional-commit prefix mix |
|
||||
| `COMMIT_SIZE_BUCKETS` | small <100 / medium 100-500 / large 500-1500 / xl 1500+ LOC per commit |
|
||||
| `HOURS` / `PEAK_HOUR` | Hourly commit histogram (local time), nonzero hours only |
|
||||
| `FOCUS_SCORE` | % of file changes in the single busiest top-level directory |
|
||||
| `BIGGEST_COMMIT` | Highest-LOC commit in the window (ship-of-the-week candidate) |
|
||||
| `HOTSPOT: count file` | Top 10 most-changed files |
|
||||
| `AUTHOR: name\|commits\|ins\|del\|test_ratio\|top_areas\|types\|peak_hour` | Per-contributor rollup, sorted by commits desc |
|
||||
| `AUTHOR_BIGGEST: name\|hash\|loc\|subject` | Each contributor's biggest ship |
|
||||
| `COAUTHOR: hash\|name` / `AI_ASSISTED_COMMITS` | Human co-author credit lines; count of commits with AI trailers |
|
||||
| `WEEK: wN\|commits\|ins\|del\|test_ratio` | Weekly buckets, w0 = newest (for Step 10 trends) |
|
||||
| `PR_REFS` / `PRS_REFERENCED` | PR/MR numbers from commit subjects (GitHub #NNN, GitLab !NNN) |
|
||||
| `TEST_FILES_TOTAL` / `TEST_FILES_CHANGED` / `REGRESSION_TEST_COMMITS` / `REGRESSION_COMMIT` | Test health: repo-wide test file count, test files changed in window, `test(qa):` / `test(design):` / `test: coverage` commits |
|
||||
| `VERSION_RANGE` | First → last VERSION file value in the window (when tracked) |
|
||||
| `TEAM_STREAK` / `USER_STREAK` | Consecutive commit days with anchor date (Step 11) |
|
||||
| `RETRO_CONTEXT` / `GREPTILE_HISTORY` / `TODOS_FILE` / `SKILL_USAGE_LOG` / `EUREKA_LOG` | Presence of optional inputs — Read the ones marked present |
|
||||
|
||||
```bash
|
||||
# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
|
||||
git log origin/<default> --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat
|
||||
**Optional inputs** (Read each file the script marks `present`):
|
||||
|
||||
# 2. Per-commit test vs total LOC breakdown with author
|
||||
# Each commit block starts with COMMIT:<hash>|<author>, followed by numstat lines.
|
||||
# Separate test files (matching test/|spec/|__tests__/) from production files.
|
||||
git log origin/<default> --since="<window>" --format="COMMIT:%H|%aN" --numstat
|
||||
|
||||
# 3. Commit timestamps for session detection and hourly distribution (with author)
|
||||
git log origin/<default> --since="<window>" --format="%at|%aN|%ai|%s" | sort -n
|
||||
|
||||
# 4. Files most frequently changed (hotspot analysis)
|
||||
git log origin/<default> --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn
|
||||
|
||||
# 5. PR/MR numbers from commit messages (GitHub #NNN, GitLab !NNN)
|
||||
git log origin/<default> --since="<window>" --format="%s" | grep -oE '[#!][0-9]+' | sort -t'#' -k1 | uniq
|
||||
|
||||
# 6. Per-author file hotspots (who touches what)
|
||||
git log origin/<default> --since="<window>" --format="AUTHOR:%aN" --name-only
|
||||
|
||||
# 7. Per-author commit counts (quick summary)
|
||||
git shortlog origin/<default> --since="<window>" -sn --no-merges
|
||||
|
||||
# 8. Greptile triage history (if available)
|
||||
cat ~/.gstack/greptile-history.md 2>/dev/null || true
|
||||
|
||||
# 9. TODOS.md backlog (if available)
|
||||
cat TODOS.md 2>/dev/null || true
|
||||
|
||||
# 10. Test file count
|
||||
git ls-files 2>/dev/null | grep -E '(\.test\.|\.spec\.|_test\.|_spec\.)' | wc -l
|
||||
|
||||
# 11. Regression test commits in window
|
||||
git log origin/<default> --since="<window>" --oneline --grep="test(qa):" --grep="test(design):" --grep="test: coverage"
|
||||
|
||||
# 12. gstack skill usage telemetry (if available)
|
||||
cat ~/.gstack/analytics/skill-usage.jsonl 2>/dev/null || true
|
||||
|
||||
# 12. Test files changed in window
|
||||
git log origin/<default> --since="<window>" --format="" --name-only | grep -E '\.(test|spec)\.' | sort -u | wc -l
|
||||
```
|
||||
- `RETRO_CONTEXT: present` → Read `~/.gstack/retro-context.md`. It is user-authored and may contain meeting notes, calendar events, decisions, and other context that doesn't appear in git history. Incorporate it into the retro narrative where relevant.
|
||||
- `GREPTILE_HISTORY: present` → Read `~/.gstack/greptile-history.md`. Filter entries to the retro window by date. Count by type: `fix`, `fp`, `already-fixed`. Signal ratio = `(fix + already-fixed) / (fix + already-fixed + fp)`. Skip unparseable lines silently; if no entries fall in the window, skip the Greptile metric row.
|
||||
- `TODOS_FILE: present` → Read `TODOS.md`. Compute: total open TODOs (exclude the `## Completed` section), P0/P1 count, P2 count, items completed this period (Completed entries dated within the window), items added this period (cross-reference `COMMIT:` lines that touched TODOS.md).
|
||||
- `SKILL_USAGE_LOG: present` → Read `~/.gstack/analytics/skill-usage.jsonl`. Filter to the window by `ts`. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name.
|
||||
- `EUREKA_LOG: present` → Read `~/.gstack/analytics/eureka.jsonl`. Filter to the window by `ts`. For each eureka moment note the skill that flagged it, the branch, and a one-line summary of the insight.
|
||||
|
||||
### Step 2: Compute Metrics
|
||||
|
||||
Calculate and present these metrics in a summary table:
|
||||
Present these metrics in a summary table, straight from the metric lines:
|
||||
|
||||
| Metric | Value |
|
||||
|--------|-------|
|
||||
| **Features shipped** (from CHANGELOG + merged PR titles) | N |
|
||||
| Commits to main | N |
|
||||
| Weighted commits (commits × avg files-touched, capped at 20 per commit) | N |
|
||||
| Weighted commits (`WEIGHTED_COMMITS`) | N |
|
||||
| Contributors | N |
|
||||
| PRs merged | N |
|
||||
| **Logical SLOC added** (non-blank, non-comment — primary code-volume metric) | N |
|
||||
| **Logical SLOC added** (`LOGICAL_SLOC_ADDED` — primary code-volume metric) | N |
|
||||
| Raw LOC: insertions | N |
|
||||
| Raw LOC: deletions | N |
|
||||
| Raw LOC: net | N |
|
||||
@@ -242,7 +191,7 @@ new functionality. Raw LOC is demoted to context because AI inflates it; ten
|
||||
lines of a good fix is not less shipping than ten thousand lines of scaffold.
|
||||
See docs/designs/PLAN_TUNING_V1.md §Workstream C.
|
||||
|
||||
Then show a **per-author leaderboard** immediately below:
|
||||
Then show a **per-author leaderboard** immediately below, from the `AUTHOR:` lines:
|
||||
|
||||
```
|
||||
Contributor Commits +/- Top area
|
||||
@@ -251,49 +200,25 @@ alice 12 +800/-150 app/services/
|
||||
bob 3 +120/-40 tests/
|
||||
```
|
||||
|
||||
Sort by commits descending. The current user (from `git config user.name`) always appears first, labeled "You (name)".
|
||||
Sort by commits descending. The current user (`USER_NAME`) always appears first, labeled "You (name)".
|
||||
|
||||
**Greptile signal (if history exists):** Read `~/.gstack/greptile-history.md` (fetched in Step 1, command 8). Filter entries within the retro time window by date. Count entries by type: `fix`, `fp`, `already-fixed`. Compute signal ratio: `(fix + already-fixed) / (fix + already-fixed + fp)`. If no entries exist in the window or the file doesn't exist, skip the Greptile metric row. Skip unparseable lines silently.
|
||||
Conditional rows (skip each when its input is absent or empty in the window):
|
||||
|
||||
**Backlog Health (if TODOS.md exists):** Read `TODOS.md` (fetched in Step 1, command 9). Compute:
|
||||
- Total open TODOs (exclude items in `## Completed` section)
|
||||
- P0/P1 count (critical/urgent items)
|
||||
- P2 count (important items)
|
||||
- Items completed this period (items in Completed section with dates within the retro window)
|
||||
- Items added this period (cross-reference git log for commits that modified TODOS.md within the window)
|
||||
|
||||
Include in the metrics table:
|
||||
```
|
||||
| Backlog Health | N open (X P0/P1, Y P2) · Z completed this period |
|
||||
```
|
||||
|
||||
If TODOS.md doesn't exist, skip the Backlog Health row.
|
||||
|
||||
**Skill Usage (if analytics exist):** Read `~/.gstack/analytics/skill-usage.jsonl` if it exists. Filter entries within the retro time window by `ts` field. Separate skill activations (no `event` field) from hook fires (`event: "hook_fire"`). Aggregate by skill name. Present as:
|
||||
|
||||
```
|
||||
| Skill Usage | /ship(12) /qa(8) /review(5) · 3 safety hook fires |
|
||||
```
|
||||
|
||||
If the JSONL file doesn't exist or has no entries in the window, skip the Skill Usage row.
|
||||
|
||||
**Eureka Moments (if logged):** Read `~/.gstack/analytics/eureka.jsonl` if it exists. Filter entries within the retro time window by `ts` field. For each eureka moment, show the skill that flagged it, the branch, and a one-line summary of the insight. Present as:
|
||||
|
||||
```
|
||||
| Eureka Moments | 2 this period |
|
||||
```
|
||||
|
||||
If moments exist, list them:
|
||||
If eureka moments exist, list them:
|
||||
```
|
||||
EUREKA /office-hours (branch: garrytan/auth-rethink): "Session tokens don't need server storage — browser crypto API makes client-side JWT validation viable"
|
||||
EUREKA /plan-eng-review (branch: garrytan/cache-layer): "Redis isn't needed here — Bun's built-in LRU cache handles this workload"
|
||||
```
|
||||
|
||||
If the JSONL file doesn't exist or has no entries in the window, skip the Eureka Moments row.
|
||||
|
||||
### Step 3: Commit Time Distribution
|
||||
|
||||
Show hourly histogram in local time using bar chart:
|
||||
Render the `HOURS` line as an hourly histogram in local time:
|
||||
|
||||
```
|
||||
Hour Commits ████████████████
|
||||
@@ -310,24 +235,14 @@ Identify and call out:
|
||||
|
||||
### Step 4: Work Session Detection
|
||||
|
||||
Detect sessions using **45-minute gap** threshold between consecutive commits. For each session report:
|
||||
- Start/end time (Pacific)
|
||||
- Number of commits
|
||||
- Duration in minutes
|
||||
|
||||
Classify sessions:
|
||||
- **Deep sessions** (50+ min)
|
||||
- **Medium sessions** (20-50 min)
|
||||
- **Micro sessions** (<20 min, typically single-commit fire-and-forget)
|
||||
|
||||
Calculate:
|
||||
- Total active coding time (sum of session durations)
|
||||
- Average session length
|
||||
- LOC per hour of active time
|
||||
Sessions are pre-computed with a **45-minute gap** threshold between consecutive commits (`SESSIONS`, `DEEP_SESSIONS` 50+ min, `MEDIUM_SESSIONS` 20-50 min, `MICRO_SESSIONS` <20 min — typically single-commit fire-and-forget). Report:
|
||||
- Session count and the deep/medium/micro split
|
||||
- Total active coding time (`TOTAL_ACTIVE_MINUTES`) and average session length
|
||||
- LOC per hour of active time (`LOC_PER_SESSION_HOUR`)
|
||||
|
||||
### Step 5: Commit Type Breakdown
|
||||
|
||||
Categorize by conventional commit prefix (feat/fix/refactor/test/chore/docs). Show as percentage bar:
|
||||
Render `COMMIT_TYPES` (feat/fix/refactor/test/chore/docs) as a percentage bar:
|
||||
|
||||
```
|
||||
feat: 20 (40%) ████████████████████
|
||||
@@ -335,18 +250,18 @@ fix: 27 (54%) ███████████████████
|
||||
refactor: 2 ( 4%) ██
|
||||
```
|
||||
|
||||
Flag if fix ratio exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
|
||||
Flag if `FIX_RATIO` exceeds 50% — this signals a "ship fast, fix fast" pattern that may indicate review gaps.
|
||||
|
||||
### Step 6: Hotspot Analysis
|
||||
|
||||
Show top 10 most-changed files. Flag:
|
||||
Show the `HOTSPOT` lines (top 10 most-changed files). Flag:
|
||||
- Files changed 5+ times (churn hotspots)
|
||||
- Test files vs production files in the hotspot list
|
||||
- VERSION/CHANGELOG frequency (version discipline indicator)
|
||||
|
||||
### Step 7: PR Size Distribution
|
||||
|
||||
From commit diffs, estimate PR sizes and bucket them:
|
||||
Report `COMMIT_SIZE_BUCKETS`:
|
||||
- **Small** (<100 LOC)
|
||||
- **Medium** (100-500 LOC)
|
||||
- **Large** (500-1500 LOC)
|
||||
@@ -354,23 +269,16 @@ From commit diffs, estimate PR sizes and bucket them:
|
||||
|
||||
### Step 8: Focus Score + Ship of the Week
|
||||
|
||||
**Focus score:** Calculate the percentage of commits touching the single most-changed top-level directory (e.g., `app/services/`, `app/views/`). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
|
||||
**Focus score:** `FOCUS_SCORE` is the percentage of file changes touching the single most-changed top-level directory (e.g., `app/services/`). Higher score = deeper focused work. Lower score = scattered context-switching. Report as: "Focus score: 62% (app/services/)"
|
||||
|
||||
**Ship of the week:** Auto-identify the single highest-LOC PR in the window. Highlight it:
|
||||
- PR number and title
|
||||
**Ship of the week:** `BIGGEST_COMMIT` is the highest-LOC change in the window. Highlight it:
|
||||
- PR number (match against `PR_REFS` / the subject) and title
|
||||
- LOC changed
|
||||
- Why it matters (infer from commit messages and files touched)
|
||||
|
||||
### Step 9: Team Member Analysis
|
||||
|
||||
For each contributor (including the current user), compute:
|
||||
|
||||
1. **Commits and LOC** — total commits, insertions, deletions, net LOC
|
||||
2. **Areas of focus** — which directories/files they touched most (top 3)
|
||||
3. **Commit type mix** — their personal feat/fix/refactor/test breakdown
|
||||
4. **Session patterns** — when they code (their peak hours), session count
|
||||
5. **Test discipline** — their personal test LOC ratio
|
||||
6. **Biggest ship** — their single highest-impact commit or PR in the window
|
||||
For each contributor (including the current user), the `AUTHOR:` line carries commits, insertions, deletions, test ratio, top areas, commit type mix, and peak hour; `AUTHOR_BIGGEST:` carries their single highest-impact commit. Use the `COMMIT:` lines to anchor everything in actual work.
|
||||
|
||||
**For the current user ("You"):** This section gets the deepest treatment. Include all the detail from the solo retro — session analysis, time patterns, focus score. Frame it in first person: "Your peak hours...", "Your biggest ship..."
|
||||
|
||||
@@ -381,7 +289,7 @@ For each contributor (including the current user), compute:
|
||||
|
||||
**If only one contributor (solo repo):** Skip the team breakdown and proceed as before — the retro is personal.
|
||||
|
||||
**If there are Co-Authored-By trailers:** Parse `Co-Authored-By:` lines in commit messages. Credit those authors for the commit alongside the primary author. Note AI co-authors (e.g., `noreply@anthropic.com`) but do not include them as team members — instead, track "AI-assisted commits" as a separate metric.
|
||||
**Co-author credit:** `COAUTHOR:` lines carry human `Co-Authored-By:` trailers — credit those authors for the commit alongside the primary author. AI co-authors (e.g., `noreply@anthropic.com`) are counted in `AI_ASSISTED_COMMITS` instead — track "AI-assisted commits" as a separate metric, never as a team member.
|
||||
|
||||
{{LEARNINGS_LOG}}
|
||||
|
||||
@@ -389,28 +297,17 @@ For each contributor (including the current user), compute:
|
||||
|
||||
### Step 10: Week-over-Week Trends (if window >= 14d)
|
||||
|
||||
If the time window is 14 days or more, split into weekly buckets and show trends:
|
||||
- Commits per week (total and per-author)
|
||||
If the time window is 14 days or more, use the `WEEK:` lines (w0 = the week containing the newest commit) to show trends:
|
||||
- Commits per week (total; per-author from the `COMMIT:` lines)
|
||||
- LOC per week
|
||||
- Test ratio per week
|
||||
- Fix ratio per week
|
||||
- Session count per week
|
||||
|
||||
### Step 11: Streak Tracking
|
||||
|
||||
Count consecutive days with at least 1 commit to origin/<default>, going back from today. Track both team streak and personal streak:
|
||||
|
||||
```bash
|
||||
# Team streak: all unique commit dates (local time) — no hard cutoff
|
||||
git log origin/<default> --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
|
||||
# Personal streak: only the current user's commits
|
||||
git log origin/<default> --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
|
||||
```
|
||||
|
||||
Count backward from today — how many consecutive days have at least one commit? This queries the full history so streaks of any length are reported accurately. Display both:
|
||||
- "Team shipping streak: 47 consecutive days"
|
||||
- "Your shipping streak: 32 consecutive days"
|
||||
`TEAM_STREAK` and `USER_STREAK` count consecutive days with at least 1 commit (full history, no cutoff), anchored at the **newest commit date** — not at today, because the script never trusts the system clock. Interpret against today from the session reminder:
|
||||
- If the anchor date is today or yesterday, the streak is live: "Team shipping streak: 47 consecutive days" / "Your shipping streak: 32 consecutive days"
|
||||
- If the anchor is older, the streak is broken: report 0 days and note the last shipping day.
|
||||
|
||||
### Step 12: Load History & Compare
|
||||
|
||||
@@ -492,7 +389,7 @@ Use the Write tool to save the JSON file with this schema:
|
||||
}
|
||||
```
|
||||
|
||||
**Note:** Only include the `greptile` field if `~/.gstack/greptile-history.md` exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (command 10 returns > 0). If any has no data, omit the field entirely.
|
||||
**Note:** Only include the `greptile` field if `~/.gstack/greptile-history.md` exists and has entries within the time window. Only include the `backlog` field if `TODOS.md` exists. Only include the `test_health` field if test files were found (`TEST_FILES_TOTAL` > 0). If any has no data, omit the field entirely.
|
||||
|
||||
Include test health data in the JSON when test files exist:
|
||||
```json
|
||||
@@ -517,124 +414,7 @@ Include backlog data in the JSON when TODOS.md exists:
|
||||
|
||||
### Step 14: Write the Narrative
|
||||
|
||||
Structure the output as:
|
||||
|
||||
---
|
||||
|
||||
**Tweetable summary** (first line, before everything else):
|
||||
```
|
||||
Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
|
||||
```
|
||||
|
||||
## Engineering Retro: [date range]
|
||||
|
||||
### Summary Table
|
||||
(from Step 2)
|
||||
|
||||
### Trends vs Last Retro
|
||||
(from Step 11, loaded before save — skip if first retro)
|
||||
|
||||
### Time & Session Patterns
|
||||
(from Steps 3-4)
|
||||
|
||||
Narrative interpreting what the team-wide patterns mean:
|
||||
- When the most productive hours are and what drives them
|
||||
- Whether sessions are getting longer or shorter over time
|
||||
- Estimated hours per day of active coding (team aggregate)
|
||||
- Notable patterns: do team members code at the same time or in shifts?
|
||||
|
||||
### Shipping Velocity
|
||||
(from Steps 5-7)
|
||||
|
||||
Narrative covering:
|
||||
- Commit type mix and what it reveals
|
||||
- PR size distribution and what it reveals about shipping cadence
|
||||
- Fix-chain detection (sequences of fix commits on the same subsystem)
|
||||
- Version bump discipline
|
||||
|
||||
### Code Quality Signals
|
||||
- Test LOC ratio trend
|
||||
- Hotspot analysis (are the same files churning?)
|
||||
- Greptile signal ratio and trend (if history exists): "Greptile: X% signal (Y valid catches, Z false positives)"
|
||||
|
||||
### Test Health
|
||||
- Total test files: N (from command 10)
|
||||
- Tests added this period: M (from command 12 — test files changed)
|
||||
- Regression test commits: list `test(qa):` and `test(design):` and `test: coverage` commits from command 11
|
||||
- If prior retro exists and has `test_health`: show delta "Test count: {last} → {now} (+{delta})"
|
||||
- If test ratio < 20%: flag as growth area — "100% test coverage is the goal. Tests make vibe coding safe."
|
||||
|
||||
### Plan Completion
|
||||
Check review JSONL logs for plan completion data from /ship runs this period:
|
||||
|
||||
```bash
|
||||
setopt +o nomatch 2>/dev/null || true # zsh compat
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
cat ~/.gstack/projects/$SLUG/*-reviews.jsonl 2>/dev/null | grep '"skill":"ship"' | grep '"plan_items_total"' || echo "NO_PLAN_DATA"
|
||||
```
|
||||
|
||||
If plan completion data exists within the retro time window:
|
||||
- Count branches shipped with plans (entries that have `plan_items_total` > 0)
|
||||
- Compute average completion: sum of `plan_items_done` / sum of `plan_items_total`
|
||||
- Identify most-skipped item category if data supports it
|
||||
|
||||
Output:
|
||||
```
|
||||
Plan Completion This Period:
|
||||
{N} branches shipped with plans
|
||||
Average completion: {X}% ({done}/{total} items)
|
||||
```
|
||||
|
||||
If no plan data exists, skip this section silently.
|
||||
|
||||
### Focus & Highlights
|
||||
(from Step 8)
|
||||
- Focus score with interpretation
|
||||
- Ship of the week callout
|
||||
|
||||
### Your Week (personal deep-dive)
|
||||
(from Step 9, for the current user only)
|
||||
|
||||
This is the section the user cares most about. Include:
|
||||
- Their personal commit count, LOC, test ratio
|
||||
- Their session patterns and peak hours
|
||||
- Their focus areas
|
||||
- Their biggest ship
|
||||
- **What you did well** (2-3 specific things anchored in commits)
|
||||
- **Where to level up** (1-2 specific, actionable suggestions)
|
||||
|
||||
### Team Breakdown
|
||||
(from Step 9, for each teammate — skip if solo repo)
|
||||
|
||||
For each teammate (sorted by commits descending), write a section:
|
||||
|
||||
#### [Name]
|
||||
- **What they shipped**: 2-3 sentences on their contributions, areas of focus, and commit patterns
|
||||
- **Praise**: 1-2 specific things they did well, anchored in actual commits. Be genuine — what would you actually say in a 1:1? Examples:
|
||||
- "Cleaned up the entire auth module in 3 small, reviewable PRs — textbook decomposition"
|
||||
- "Added integration tests for every new endpoint, not just happy paths"
|
||||
- "Fixed the N+1 query that was causing 2s load times on the dashboard"
|
||||
- **Opportunity for growth**: 1 specific, constructive suggestion. Frame as investment, not criticism. Examples:
|
||||
- "Test coverage on the payment module is at 8% — worth investing in before the next feature lands on top of it"
|
||||
- "Most commits land in a single burst — spacing work across the day could reduce context-switching fatigue"
|
||||
- "All commits land between 1-4am — sustainable pace matters for code quality long-term"
|
||||
|
||||
**AI collaboration note:** If many commits have `Co-Authored-By` AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
|
||||
|
||||
### Top 3 Team Wins
|
||||
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
|
||||
- What it was
|
||||
- Who shipped it
|
||||
- Why it matters (product/architecture impact)
|
||||
|
||||
### 3 Things to Improve
|
||||
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
|
||||
|
||||
### 3 Habits for Next Week
|
||||
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
|
||||
|
||||
### Week-over-Week Trends
|
||||
(if applicable, from Step 10)
|
||||
{{SECTION:report-format}}
|
||||
|
||||
---
|
||||
|
||||
@@ -931,8 +711,8 @@ Use the Write tool to save JSON to `~/.gstack/retros/global-${today}-${next}.jso
|
||||
|
||||
When the user runs `/retro compare` (or `/retro compare 14d`):
|
||||
|
||||
1. Compute metrics for the current window (default 7d) using the midnight-aligned start date (same logic as the main retro — e.g., if today is 2026-03-18 and window is 7d, use `--since="2026-03-11T00:00:00"`)
|
||||
2. Compute metrics for the immediately prior same-length window using both `--since` and `--until` with midnight-aligned dates to avoid overlap (e.g., for a 7d window starting 2026-03-11: prior window is `--since="2026-03-04T00:00:00" --until="2026-03-11T00:00:00"`)
|
||||
1. Run Steps 0.5-1 for the current window (default 7d) using the midnight-aligned start date (same logic as the main retro — e.g., if today is 2026-03-18 and window is 7d, `--since "2026-03-11T00:00:00"`)
|
||||
2. Run `gstack-retro-metrics` a second time for the immediately prior same-length window, using both `--since` and `--until` with midnight-aligned dates to avoid overlap (e.g., for a 7d window starting 2026-03-11: `--since "2026-03-04T00:00:00" --until "2026-03-11T00:00:00"`)
|
||||
3. Show a side-by-side comparison table with deltas and arrows
|
||||
4. Write a brief narrative highlighting the biggest improvements and regressions
|
||||
5. Save only the current-window snapshot to `.context/retros/` (same as a normal retro run); do **not** persist the prior-window metrics.
|
||||
@@ -953,10 +733,10 @@ When the user runs `/retro compare` (or `/retro compare 14d`):
|
||||
## Important Rules
|
||||
|
||||
- ALL narrative output goes directly to the user in the conversation. The ONLY file written is the `.context/retros/` JSON snapshot.
|
||||
- Use `origin/<default>` for all git queries (not local main which may be stale)
|
||||
- The metrics script analyzes `origin/<default>` (not local main which may be stale); when `RETRO_REF` says otherwise, disclose it
|
||||
- Display all timestamps in the user's local timezone (do not override `TZ`)
|
||||
- If the window has zero commits, say so and suggest a different window
|
||||
- Round LOC/hour to nearest 50
|
||||
- If `COMMITS: 0`, say so and suggest a different window
|
||||
- Round LOC/hour to nearest 50 (the script pre-rounds `LOC_PER_SESSION_HOUR`)
|
||||
- Treat merge commits as PR boundaries
|
||||
- Do not read CLAUDE.md or other docs — this skill is self-contained
|
||||
- On first run (no prior retros), skip comparison sections gracefully
|
||||
|
||||
@@ -0,0 +1,14 @@
|
||||
{
|
||||
"$schema": "https://gstack.dev/schemas/section-manifest.json",
|
||||
"skill": "retro",
|
||||
"version": 1,
|
||||
"note": "PASSIVE registry (v2 plan T9 / CM2). id/file/title/trigger text ONLY. The skeleton's decision-tree prose decides WHEN to read. No machine predicate here.",
|
||||
"sections": [
|
||||
{
|
||||
"id": "report-format",
|
||||
"file": "report-format.md",
|
||||
"title": "Narrative report structure — tweetable summary, section-by-section output template, Test Health, Plan Completion, personal deep-dive, team breakdown, wins/improvements/habits (Step 14)",
|
||||
"trigger": "writing the retrospective narrative (Step 14, after all metrics are computed and compared)"
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,120 @@
|
||||
<!-- AUTO-GENERATED from report-format.md.tmpl — do not edit directly -->
|
||||
<!-- Regenerate: bun run gen:skill-docs -->
|
||||
Structure the output as:
|
||||
|
||||
---
|
||||
|
||||
**Tweetable summary** (first line, before everything else):
|
||||
```
|
||||
Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
|
||||
```
|
||||
|
||||
## Engineering Retro: [date range]
|
||||
|
||||
### Summary Table
|
||||
(from Step 2)
|
||||
|
||||
### Trends vs Last Retro
|
||||
(from Step 12, loaded before save — skip if first retro)
|
||||
|
||||
### Time & Session Patterns
|
||||
(from Steps 3-4)
|
||||
|
||||
Narrative interpreting what the team-wide patterns mean:
|
||||
- When the most productive hours are and what drives them
|
||||
- Whether sessions are getting longer or shorter over time
|
||||
- Estimated hours per day of active coding (team aggregate)
|
||||
- Notable patterns: do team members code at the same time or in shifts?
|
||||
|
||||
### Shipping Velocity
|
||||
(from Steps 5-7)
|
||||
|
||||
Narrative covering:
|
||||
- Commit type mix and what it reveals
|
||||
- PR size distribution and what it reveals about shipping cadence
|
||||
- Fix-chain detection (sequences of fix commits on the same subsystem)
|
||||
- Version bump discipline
|
||||
|
||||
### Code Quality Signals
|
||||
- Test LOC ratio trend
|
||||
- Hotspot analysis (are the same files churning?)
|
||||
- Greptile signal ratio and trend (if history exists): "Greptile: X% signal (Y valid catches, Z false positives)"
|
||||
|
||||
### Test Health
|
||||
- Total test files: N (`TEST_FILES_TOTAL`)
|
||||
- Tests added this period: M (`TEST_FILES_CHANGED` — test files changed in the window)
|
||||
- Regression test commits: list the `REGRESSION_COMMIT` lines (`test(qa):`, `test(design):`, and `test: coverage` commits)
|
||||
- If prior retro exists and has `test_health`: show delta "Test count: {last} → {now} (+{delta})"
|
||||
- If test ratio < 20%: flag as growth area — "100% test coverage is the goal. Tests make vibe coding safe."
|
||||
|
||||
### Plan Completion
|
||||
Check review JSONL logs for plan completion data from /ship runs this period:
|
||||
|
||||
```bash
|
||||
setopt +o nomatch 2>/dev/null || true # zsh compat
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
cat ~/.gstack/projects/$SLUG/*-reviews.jsonl 2>/dev/null | grep '"skill":"ship"' | grep '"plan_items_total"' || echo "NO_PLAN_DATA"
|
||||
```
|
||||
|
||||
If plan completion data exists within the retro time window:
|
||||
- Count branches shipped with plans (entries that have `plan_items_total` > 0)
|
||||
- Compute average completion: sum of `plan_items_done` / sum of `plan_items_total`
|
||||
- Identify most-skipped item category if data supports it
|
||||
|
||||
Output:
|
||||
```
|
||||
Plan Completion This Period:
|
||||
{N} branches shipped with plans
|
||||
Average completion: {X}% ({done}/{total} items)
|
||||
```
|
||||
|
||||
If no plan data exists, skip this section silently.
|
||||
|
||||
### Focus & Highlights
|
||||
(from Step 8)
|
||||
- Focus score with interpretation
|
||||
- Ship of the week callout
|
||||
|
||||
### Your Week (personal deep-dive)
|
||||
(from Step 9, for the current user only)
|
||||
|
||||
This is the section the user cares most about. Include:
|
||||
- Their personal commit count, LOC, test ratio
|
||||
- Their session patterns and peak hours
|
||||
- Their focus areas
|
||||
- Their biggest ship
|
||||
- **What you did well** (2-3 specific things anchored in commits)
|
||||
- **Where to level up** (1-2 specific, actionable suggestions)
|
||||
|
||||
### Team Breakdown
|
||||
(from Step 9, for each teammate — skip if solo repo)
|
||||
|
||||
For each teammate (sorted by commits descending), write a section:
|
||||
|
||||
#### [Name]
|
||||
- **What they shipped**: 2-3 sentences on their contributions, areas of focus, and commit patterns
|
||||
- **Praise**: 1-2 specific things they did well, anchored in actual commits. Be genuine — what would you actually say in a 1:1? Examples:
|
||||
- "Cleaned up the entire auth module in 3 small, reviewable PRs — textbook decomposition"
|
||||
- "Added integration tests for every new endpoint, not just happy paths"
|
||||
- "Fixed the N+1 query that was causing 2s load times on the dashboard"
|
||||
- **Opportunity for growth**: 1 specific, constructive suggestion. Frame as investment, not criticism. Examples:
|
||||
- "Test coverage on the payment module is at 8% — worth investing in before the next feature lands on top of it"
|
||||
- "Most commits land in a single burst — spacing work across the day could reduce context-switching fatigue"
|
||||
- "All commits land between 1-4am — sustainable pace matters for code quality long-term"
|
||||
|
||||
**AI collaboration note:** If many commits have `Co-Authored-By` AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
|
||||
|
||||
### Top 3 Team Wins
|
||||
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
|
||||
- What it was
|
||||
- Who shipped it
|
||||
- Why it matters (product/architecture impact)
|
||||
|
||||
### 3 Things to Improve
|
||||
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
|
||||
|
||||
### 3 Habits for Next Week
|
||||
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
|
||||
|
||||
### Week-over-Week Trends
|
||||
(if applicable, from Step 10)
|
||||
@@ -0,0 +1,118 @@
|
||||
Structure the output as:
|
||||
|
||||
---
|
||||
|
||||
**Tweetable summary** (first line, before everything else):
|
||||
```
|
||||
Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
|
||||
```
|
||||
|
||||
## Engineering Retro: [date range]
|
||||
|
||||
### Summary Table
|
||||
(from Step 2)
|
||||
|
||||
### Trends vs Last Retro
|
||||
(from Step 12, loaded before save — skip if first retro)
|
||||
|
||||
### Time & Session Patterns
|
||||
(from Steps 3-4)
|
||||
|
||||
Narrative interpreting what the team-wide patterns mean:
|
||||
- When the most productive hours are and what drives them
|
||||
- Whether sessions are getting longer or shorter over time
|
||||
- Estimated hours per day of active coding (team aggregate)
|
||||
- Notable patterns: do team members code at the same time or in shifts?
|
||||
|
||||
### Shipping Velocity
|
||||
(from Steps 5-7)
|
||||
|
||||
Narrative covering:
|
||||
- Commit type mix and what it reveals
|
||||
- PR size distribution and what it reveals about shipping cadence
|
||||
- Fix-chain detection (sequences of fix commits on the same subsystem)
|
||||
- Version bump discipline
|
||||
|
||||
### Code Quality Signals
|
||||
- Test LOC ratio trend
|
||||
- Hotspot analysis (are the same files churning?)
|
||||
- Greptile signal ratio and trend (if history exists): "Greptile: X% signal (Y valid catches, Z false positives)"
|
||||
|
||||
### Test Health
|
||||
- Total test files: N (`TEST_FILES_TOTAL`)
|
||||
- Tests added this period: M (`TEST_FILES_CHANGED` — test files changed in the window)
|
||||
- Regression test commits: list the `REGRESSION_COMMIT` lines (`test(qa):`, `test(design):`, and `test: coverage` commits)
|
||||
- If prior retro exists and has `test_health`: show delta "Test count: {last} → {now} (+{delta})"
|
||||
- If test ratio < 20%: flag as growth area — "100% test coverage is the goal. Tests make vibe coding safe."
|
||||
|
||||
### Plan Completion
|
||||
Check review JSONL logs for plan completion data from /ship runs this period:
|
||||
|
||||
```bash
|
||||
setopt +o nomatch 2>/dev/null || true # zsh compat
|
||||
eval "$(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)"
|
||||
cat ~/.gstack/projects/$SLUG/*-reviews.jsonl 2>/dev/null | grep '"skill":"ship"' | grep '"plan_items_total"' || echo "NO_PLAN_DATA"
|
||||
```
|
||||
|
||||
If plan completion data exists within the retro time window:
|
||||
- Count branches shipped with plans (entries that have `plan_items_total` > 0)
|
||||
- Compute average completion: sum of `plan_items_done` / sum of `plan_items_total`
|
||||
- Identify most-skipped item category if data supports it
|
||||
|
||||
Output:
|
||||
```
|
||||
Plan Completion This Period:
|
||||
{N} branches shipped with plans
|
||||
Average completion: {X}% ({done}/{total} items)
|
||||
```
|
||||
|
||||
If no plan data exists, skip this section silently.
|
||||
|
||||
### Focus & Highlights
|
||||
(from Step 8)
|
||||
- Focus score with interpretation
|
||||
- Ship of the week callout
|
||||
|
||||
### Your Week (personal deep-dive)
|
||||
(from Step 9, for the current user only)
|
||||
|
||||
This is the section the user cares most about. Include:
|
||||
- Their personal commit count, LOC, test ratio
|
||||
- Their session patterns and peak hours
|
||||
- Their focus areas
|
||||
- Their biggest ship
|
||||
- **What you did well** (2-3 specific things anchored in commits)
|
||||
- **Where to level up** (1-2 specific, actionable suggestions)
|
||||
|
||||
### Team Breakdown
|
||||
(from Step 9, for each teammate — skip if solo repo)
|
||||
|
||||
For each teammate (sorted by commits descending), write a section:
|
||||
|
||||
#### [Name]
|
||||
- **What they shipped**: 2-3 sentences on their contributions, areas of focus, and commit patterns
|
||||
- **Praise**: 1-2 specific things they did well, anchored in actual commits. Be genuine — what would you actually say in a 1:1? Examples:
|
||||
- "Cleaned up the entire auth module in 3 small, reviewable PRs — textbook decomposition"
|
||||
- "Added integration tests for every new endpoint, not just happy paths"
|
||||
- "Fixed the N+1 query that was causing 2s load times on the dashboard"
|
||||
- **Opportunity for growth**: 1 specific, constructive suggestion. Frame as investment, not criticism. Examples:
|
||||
- "Test coverage on the payment module is at 8% — worth investing in before the next feature lands on top of it"
|
||||
- "Most commits land in a single burst — spacing work across the day could reduce context-switching fatigue"
|
||||
- "All commits land between 1-4am — sustainable pace matters for code quality long-term"
|
||||
|
||||
**AI collaboration note:** If many commits have `Co-Authored-By` AI trailers (e.g., Claude, Copilot), note the AI-assisted commit percentage as a team metric. Frame it neutrally — "N% of commits were AI-assisted" — without judgment.
|
||||
|
||||
### Top 3 Team Wins
|
||||
Identify the 3 highest-impact things shipped in the window across the whole team. For each:
|
||||
- What it was
|
||||
- Who shipped it
|
||||
- Why it matters (product/architecture impact)
|
||||
|
||||
### 3 Things to Improve
|
||||
Specific, actionable, anchored in actual commits. Mix personal and team-level suggestions. Phrase as "to get even better, the team could..."
|
||||
|
||||
### 3 Habits for Next Week
|
||||
Small, practical, realistic. Each must be something that takes <5 minutes to adopt. At least one should be team-oriented (e.g., "review each other's PRs same-day").
|
||||
|
||||
### Week-over-Week Trends
|
||||
(if applicable, from Step 10)
|
||||
Reference in New Issue
Block a user