ytstack:retro
Adapted from gstack's retro skill (MIT, Garry Tan), baseline in metadata.upstream; see NOTICE.
A milestone retrospective with two kinds of evidence: what the task summaries say happened (outcome, deviations, follow-ups, verification) and what git says happened (commits, sessions, hotspots, test share, shipping pace). The result is M###-RETRO.md next to the milestone, plus lessons copied into KNOWLEDGE.md and DECISIONS.md with the user's consent. Differs from upstream: scoped to a milestone instead of a calendar week, history lives in prior M###-RETRO.md files, no global cross-project mode.
Anti-Pattern: "The summaries already say what happened, skip the git data"
Summaries are written by the agent that did the work, right after it did it. They describe intent and outcome; they do not show that one file churned 14 times, that 60% of the commits were fixes, or that every session ran past midnight. Git is the second witness. A retro built from summaries alone repeats what everyone already believes. Run the metrics, then let the two sources argue with each other: a summary that says "clean" next to a fix chain on the same file is the finding.
Checklist
You MUST create a task for each of these items and complete them in order:
- Run preamble -- resolver, milestone, summary count, window anchors, base branch, prior retro
- HARD-GATE -- stop without a milestone or without summaries
- Read the material -- every
M###-S##-T##-SUMMARY.md, M###-CONTEXT.md, M###-ROADMAP.md, the slice plans, PRIOR_RETRO
- Fix the window -- milestone window by default, or the user's
<N>d|h|w / compare argument
- Gather metrics -- one bash command, then the freshness guard
- Shipping outcomes -- merged PRs (only if
HAS_GH=yes), CHANGELOG features, backlog (only if TODOS=yes)
- Analyze -- time, sessions, commit types, hotspots, sizes, focus, ship of the milestone, people, streaks
- Milestone outcomes -- exit criteria vs summaries, deviations, open follow-ups, plan completion; own reviewers vs bots (only if
OWN_REVIEWERS is not none); incidents and repeats per class (only if LESSONS is above 0)
- Compare with the prior retro (only if
PRIOR_RETRO is not none, or in compare mode) -- trends + recommendation follow-through
- Ask before replacing (only if
RETRO_EXISTS=yes) -- replace or stop
- Write
M###-RETRO.md -- frontmatter + report + snapshot, and show the report in the conversation
- Propose lessons -- KNOWLEDGE / DECISIONS entries, ask once, write what the user accepts
- Upstream -- what of this milestone concerns ytstack itself, handled per
UPSTREAM_FEEDBACK, recorded under ## Upstream
- Report + return -- paths, entry counts, upstream lines, next-step suggestion, no auto-chaining
Process Flow
digraph retro {
"Start" [shape=doublecircle];
"Milestone + summaries?" [shape=diamond];
"Stop: nothing to review" [shape=doublecircle];
"Read summaries + context" [shape=box];
"Window + metrics" [shape=box];
"Window stale?" [shape=diamond];
"Stop: fix date or fetch" [shape=doublecircle];
"Analyze + milestone outcomes" [shape=box];
"Compare with prior retro" [shape=box];
"RETRO exists?" [shape=diamond];
"Write M###-RETRO.md" [shape=box];
"Ask: lessons" [shape=diamond];
"Upstream per setting" [shape=box];
"Report" [shape=doublecircle];
"Start" -> "Milestone + summaries?";
"Milestone + summaries?" -> "Stop: nothing to review" [label="no"];
"Milestone + summaries?" -> "Read summaries + context" [label="yes"];
"Read summaries + context" -> "Window + metrics";
"Window + metrics" -> "Window stale?";
"Window stale?" -> "Stop: fix date or fetch" [label="yes"];
"Window stale?" -> "Analyze + milestone outcomes" [label="no"];
"Analyze + milestone outcomes" -> "Compare with prior retro";
"Compare with prior retro" -> "RETRO exists?";
"RETRO exists?" -> "Write M###-RETRO.md" [label="no / replace"];
"RETRO exists?" -> "Report" [label="keep"];
"Write M###-RETRO.md" -> "Ask: lessons";
"Ask: lessons" -> "Upstream per setting";
"Upstream per setting" -> "Report";
}
Preamble
Resolved when the skill loads:
# ytstack resolver (M016): checkout = where this shell runs, via the shared lib.
_LIB="${CLAUDE_SKILL_DIR}/../../hooks/lib/git-ctx.sh"
if [ -f "$_LIB" ]; then
. "$_LIB"; yt_git_ctx "$PWD"; yt_resolve_yt_dir >/dev/null
_PROJECT_DIR="$YT_TOPLEVEL"; _YT_DIR="$YT_DIR"; _YT_SCOPE="$YT_SCOPE"; _IS_GIT="$YT_IS_GIT"; _PROJECT_KEY="$YT_REPO_KEY"
else
# Host did not substitute CLAUDE_SKILL_DIR (e.g. Codex adapter): project scope only.
_IS_GIT=$([ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ] && echo yes || echo no)
_PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)
_YT_DIR=""; _YT_SCOPE=none; _PROJECT_KEY=""
[ -d "$_PROJECT_DIR/.ytstack" ] && { _YT_DIR="$_PROJECT_DIR/.ytstack"; _YT_SCOPE=project; }
fi
cd "$_PROJECT_DIR" 2>/dev/null || true
_PROJECT_SLUG=$(basename "$_PROJECT_DIR") # display only
_HAS_YTSTACK=$([ -n "$_YT_DIR" ] && echo yes || echo no)
echo "BRANCH: $(git branch --show-current 2>/dev/null || echo unknown)"
echo "PROJECT_SLUG: $_PROJECT_SLUG"
echo "HAS_YTSTACK: $_HAS_YTSTACK"
echo "YTSTACK_SCOPE: $_YT_SCOPE"
echo "YT_DIR: $_YT_DIR"
if [ -n "$YTSTACK_NON_INTERACTIVE" ] || [ -n "$OPENCLAW_SESSION" ] || [ -n "$CLAUDE_AGENT_TEAM_MEMBER" ]; then
echo "YTSTACK_NON_INTERACTIVE: true"
else
echo "YTSTACK_NON_INTERACTIVE: false"
fi
if [ -f "$_YT_DIR/STATE.md" ]; then
echo "CURRENT_MILESTONE: $(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1)"
echo "ACTIVE_SLICE: $(sed -n 's/^active_slice: *//p' "$_YT_DIR/STATE.md" | head -1)"
fi
# Milestone to review: the current one.
_M=none; _SUMMARIES=0; _RETRO_FILE=none; _PRIOR=none; _FIRST=none; _CREATED=none; _TASKS_DONE=0; _TASKS_ALL=0
if [ -n "$_YT_DIR" ] && [ -f "$_YT_DIR/STATE.md" ]; then
_M=$(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1); _M=${_M:-none}
if [ "$_M" != none ]; then
_SUMMARIES=$(ls "$_YT_DIR"/$_M-S[0-9][0-9]-T[0-9][0-9]-SUMMARY.md 2>/dev/null | grep -c .)
_RETRO_FILE="$_YT_DIR/$_M-RETRO.md"
_PRIOR=$(ls "$_YT_DIR"/M[0-9][0-9][0-9]-RETRO.md 2>/dev/null | grep -v "/$_M-RETRO.md" | sort | tail -1); _PRIOR=${_PRIOR:-none}
[ -f "$_YT_DIR/$_M-CONTEXT.md" ] && _CREATED=$(sed -n 's/^created: *//p' "$_YT_DIR/$_M-CONTEXT.md" | head -1 | cut -c1-10)
_CREATED=${_CREATED:-none}
if command -v yt_commit_ref_pattern >/dev/null 2>&1; then
_PAT=$(yt_commit_ref_pattern "$_YT_DIR" "$_M" 'S[0-9][0-9]' 'T[0-9][0-9]')
else
_PAT="^$_M-S[0-9][0-9]-T[0-9][0-9]:"
fi
_FIRST=$(git log --no-merges -E --grep "$_PAT" --date=format-local:%Y-%m-%d --format=%ad 2>/dev/null | tail -1); _FIRST=${_FIRST:-none}
_TASKS_DONE=$(cat "$_YT_DIR"/$_M-S[0-9][0-9]-PLAN.md 2>/dev/null | grep -cE '^- \[[xX]\] T[0-9][0-9]')
_TASKS_ALL=$(cat "$_YT_DIR"/$_M-S[0-9][0-9]-PLAN.md 2>/dev/null | grep -cE '^- \[[ xX]\] T[0-9][0-9]')
fi
fi
_BASE=$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')
for _C in main master; do [ -n "$_BASE" ] && break; git rev-parse --verify --quiet "$_C" >/dev/null 2>&1 && _BASE=$_C; done
echo "MILESTONE: $_M"
echo "SUMMARIES: $_SUMMARIES"
echo "RETRO_FILE: $_RETRO_FILE"
echo "RETRO_EXISTS: $([ -f "$_RETRO_FILE" ] && echo yes || echo no)"
echo "PRIOR_RETRO: $_PRIOR"
echo "FIRST_TASK_COMMIT: $_FIRST"
echo "CONTEXT_CREATED: $_CREATED"
echo "PLAN_TASKS: $_TASKS_DONE/$_TASKS_ALL done"
echo "BASE_BRANCH: ${_BASE:-$(git branch --show-current 2>/dev/null)}"
echo "USER_NAME: $(git config user.name 2>/dev/null || echo unknown)"
echo "HAS_GH: $(command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 && echo yes || echo no)"
echo "CHANGELOG: $([ -f "$_PROJECT_DIR/CHANGELOG.md" ] && echo yes || echo no)"
echo "TODOS: $([ -f "$_PROJECT_DIR/TODOS.md" ] && echo yes || echo no)"
# Own reviewers (M030): the roles of REVIEW.md and the escape records of the signals ledger.
_RISK="${CLAUDE_SKILL_DIR}/../../bin/ytstack-risk"; [ -f "$_RISK" ] || _RISK=$(command -v ytstack-risk 2>/dev/null)
_SIG="${CLAUDE_SKILL_DIR}/../../bin/ytstack-signals"; [ -f "$_SIG" ] || _SIG=$(command -v ytstack-signals 2>/dev/null)
_ROLES=""; [ -n "$_RISK" ] && _ROLES=$(bash "$_RISK" -C "$_PROJECT_DIR" reviewers 2>/dev/null | cut -f1 | tr '\n' ' ')
echo "OWN_REVIEWERS: ${_ROLES:-none}"
if [ -n "$_ROLES" ] && [ -n "$_SIG" ]; then
echo "REVIEW_FINDINGS_BEGIN"
bash "$_SIG" -C "$_PROJECT_DIR" list --state all 2>/dev/null | awk -F'\t' '$4 == "review"'
echo "REVIEW_FINDINGS_END"
fi
# Lessons (M032): every incident of any class left one in the signals ledger; step 8 counts them per class for the window.
echo "LESSONS: $([ -n "$_SIG" ] && [ -n "$_YT_DIR" ] && bash "$_SIG" -C "$_PROJECT_DIR" lesson list --state all 2>/dev/null | awk 'NF { n++ } END { print n + 0 }' || echo 0)"
echo "SIGNALS_TOOL: ${_SIG:-unavailable}"
# Upstream feedback (M033): the effective setting; the rules are docs/ux/upstream-feedback.md.
_UP="${CLAUDE_SKILL_DIR}/../../bin/ytstack-upstream"; [ -f "$_UP" ] || _UP=$(command -v ytstack-upstream 2>/dev/null)
_UPM=""; [ -n "$_UP" ] && _UPM=$(bash "$_UP" -C "$_PROJECT_DIR" mode 2>/dev/null | sed -n 's/^mode: //p')
echo "UPSTREAM_FEEDBACK: ${_UPM:-unavailable}"
echo "UPSTREAM_TOOL: ${_UP:-unavailable}"
Procedure
Today is the date in the session context (currentDate), never the output of date: the system clock in a container can be hours off. If the session carries no date, ask the user for today's date in one short open question (re-ground: project, branch, "I need today's date to set the retro window") and wait. In YTSTACK_NON_INTERACTIVE: true mode, stop with "no reliable date; pass today's date in the brief" instead.
All times are the user's local timezone. Never set TZ.
1. Run preamble
The preamble above ran when the skill loaded. Read its flags; refer to them by name below.
2. HARD-GATE
- If
HAS_YTSTACK is no or MILESTONE is none: stop with "no milestone to review; run ytstack:resume-session".
- If
SUMMARIES is 0: stop with "the milestone has no task summaries yet; retro runs after the last ytstack:summarize-task".
- Otherwise continue. If
PLAN_TASKS shows open tasks (done below total), say once that the retro covers a milestone with unfinished tasks and name them in the Milestone Outcomes section; do not stop.
3. Read the material
Read, with the Read tool, in this order: <YT_DIR>/<MILESTONE>-CONTEXT.md (goal, exit criteria, decisions locked during discuss), <YT_DIR>/<MILESTONE>-ROADMAP.md, every <YT_DIR>/<MILESTONE>-S##-PLAN.md, every <YT_DIR>/<MILESTONE>-S##-T##-SUMMARY.md (Commits, Outcome, Deviations, Follow-ups, Verification and the verification: frontmatter key), and PRIOR_RETRO when it is not none (its ## Snapshot block holds the metrics and recommendations to compare against).
Do not read unrelated docs. CHANGELOG.md and TODOS.md are read in step 6, nothing else outside .ytstack/.
4. Fix the window
Default: the milestone window. Start = FIRST_TASK_COMMIT, else CONTEXT_CREATED, else 14 days before today. End = now. Align the start to local midnight: --since "<start>T00:00:00" (without the T00:00:00 suffix git uses the current wall-clock time of that day).
The user may override with an argument:
<N>d / <N>w -- the last N days (weeks x 7), midnight-aligned.
<N>h -- --since "<N> hours ago", no midnight alignment.
compare or compare <N>d -- the window (milestone window by default) plus the immediately prior window of the same length. The prior window ends one second before the current start (--until "<day before start>T23:59:59"), because git includes the --until boundary and a commit must not count twice.
Any other argument: show this usage and stop.
Usage: ytstack:retro [window | compare [window]]
ytstack:retro -- the milestone window (first task commit .. now)
ytstack:retro 14d -- last 14 days instead
ytstack:retro 24h -- last 24 hours
ytstack:retro compare -- milestone window vs the prior window of the same length
Say the window in one line before running the metrics: "Window: 2026-11-01 .. today (milestone M016, from the first task commit)".
5. Gather metrics
Run this once. Substitute <since> (for example 2026-11-01T00:00:00), <until> (empty for the current window) and <base> (BASE_BRANCH). In compare mode run it a second time for the prior window with both <since> and <until> set, and keep the two outputs apart.
_SINCE="<since>"; _UNTIL="<until>"; _BASE="<base>"
# Freshness: refresh the base ref; offline or no remote is fine, the guard discloses it.
git fetch origin "$_BASE" --quiet 2>/dev/null && echo "RETRO_FETCH: ok" || echo "RETRO_FETCH: failed (offline or no remote)"
# Analyzed ref: always HEAD, so the milestone's own commits are counted even
# before the branch has merged the latest base. Divergence is only reported.
_REF=HEAD; _BEHIND=0
for _C in "origin/$_BASE" "$_BASE"; do
git rev-parse --verify --quiet "$_C" >/dev/null 2>&1 || continue
_BEHIND=$(git rev-list --count "HEAD..$_C" 2>/dev/null || echo 0)
break
done
echo "RETRO_REF: $_REF"
echo "BASE_COMMITS_NOT_IN_HEAD: $_BEHIND"
echo "GUARD_REMOTE: $(git remote 2>/dev/null | grep -qx origin && echo origin || echo none)"
echo "GUARD_LATEST_COMMIT: $(git log -1 --date=format-local:%Y-%m-%d --format=%ad "$_REF" 2>/dev/null || echo unknown)"
echo "WINDOW: $_SINCE .. ${_UNTIL:-now}"
# One numstat walk over the window -> every per-commit metric.
git log "$_REF" --no-merges --since="$_SINCE" ${_UNTIL:+--until="$_UNTIL"} \
--date=format-local:'%Y-%m-%d %H' --numstat \
--format='C|%h|%aN|%at|%ad|%(trailers:key=Co-authored-by,valueonly,separator=;)|%s' 2>/dev/null | awk -F'\t' '
function gen(p) { return p ~ /(^|\/)(build|dist|out|target|vendor|node_modules|\.next|coverage|__pycache__)\// }
function prose(p) { return p ~ /\.(md|mdx|txt|rst|adoc)$/ || p ~ /(^|\/)docs?\// }
function istest(p) { return !prose(p) && (p ~ /(^|\/)(tests?|specs?|__tests__)\// || p ~ /(\.|_)(test|spec)\./ || p ~ /(^|\/)test_[^\/]*\.(py|rb)$/ || p ~ /\.bats$/) }
function endsess() { L = (last - first) / 60; tot += L; if (L >= 50) deep++; else if (L >= 20) med++; else mic++ }
function flush() {
if (h == "") return
loc = ci + cd; nc++; ins += ci; del += cd; tins += ti
ai[a] += ci; ad[a] += cd; at[a] += ti
if (loc < 100) b1++; else if (loc < 500) b2++; else if (loc < 1500) b3++; else b4++
if (loc > bigloc) { bigloc = loc; big = h " " loc " LOC -- " s }
if (loc > abig[a]) { abig[a] = loc; abs[a] = h " " loc " LOC -- " s }
wc += (cf > 20 ? 20 : cf)
}
/^C\|/ {
flush(); n = split($0, f, "|"); h = f[2]; a = f[3]; ep[++ne] = f[4]
s = f[7]; for (i = 8; i <= n; i++) s = s "|" f[i]
split(f[5], dh, " "); day[dh[1]] = 1; hr[dh[2] + 0]++
ac[a]++; if (!(a in seen)) { seen[a] = 1; na++; an[na] = a }
if (f[6] ~ /noreply@anthropic\.com|[Cc]laude|[Cc]opilot|[Cc]odex|[Cc]ursor/) aia++
nco = split(f[6], co, ";"); for (i = 1; i <= nco; i++) if (co[i] != "" && co[i] !~ /noreply@anthropic\.com|[Cc]laude|[Cc]opilot|[Cc]odex|[Cc]ursor/) print "COAUTHOR: " h "|" co[i]
t = "other"
if (s ~ /^M[0-9][0-9][0-9]-S[0-9][0-9]-T[0-9][0-9]:/) t = "task"
else if (match(s, /^[a-z]+(\([^)]*\))?!?:/)) { t = substr(s, 1, RLENGTH); sub(/[(!:].*/, "", t) }
ty[t]++; if (!(t in tseen)) { tseen[t] = 1; nt++; tn[nt] = t }
while (match(s, /#[0-9]+/)) { prs = prs " " substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH) }
s = f[7]; for (i = 8; i <= n; i++) s = s "|" f[i]
print "COMMIT: " h "|" a "|" f[5] ":00|" s
ci = 0; cd = 0; ti = 0; cf = 0; next
}
NF >= 3 && $1 != "" {
p = $3; if (gen(p)) next
x = ($1 == "-" ? 0 : $1); y = ($2 == "-" ? 0 : $2)
ci += x; cd += y; cf++; hot[p]++
if (istest(p)) ti += x
d = p; sub(/\/.*/, "/", d); if (d == p) d = "(root)"; dir[d]++; ndf++
}
END {
flush()
print "COMMITS: " nc + 0; print "CONTRIBUTORS: " na + 0
print "INSERTIONS: " ins + 0; print "DELETIONS: " del + 0; print "NET_LOC: " ins - del
print "TEST_INSERTIONS: " tins + 0; print "TEST_RATIO: " (ins ? int(100 * tins / ins) : 0) "%"
print "WEIGHTED_COMMITS: " wc + 0
nd = 0; for (k in day) nd++; print "ACTIVE_DAYS: " nd
# Sessions: a gap of more than 45 minutes between commits starts a new one (log is newest first).
ns = 0; deep = 0; med = 0; mic = 0; tot = 0
for (i = ne; i >= 1; i--) {
if (i < ne && ep[i] - ep[i + 1] > 2700) endsess()
if (i == ne || ep[i] - ep[i + 1] > 2700) { ns++; first = ep[i] }
last = ep[i]
}
if (ne) endsess()
print "SESSIONS: " ns " (deep " deep + 0 ", medium " med + 0 ", micro " mic + 0 ")"
print "TOTAL_ACTIVE_MINUTES: " int(tot); print "AVG_SESSION_MINUTES: " (ns ? int(tot / ns) : 0)
print "LOC_PER_SESSION_HOUR: " (tot > 0 ? int(ins / (tot / 60) / 50 + 0.5) * 50 : "n/a")
line = ""; for (i = 1; i <= nt; i++) line = line " " tn[i] "=" ty[tn[i]]; print "COMMIT_TYPES:" line
print "FIX_RATIO: " (nc ? int(100 * ty["fix"] / nc) : 0) "%"
print "COMMIT_SIZE_BUCKETS: small=" b1 + 0 " medium=" b2 + 0 " large=" b3 + 0 " xl=" b4 + 0
line = ""; pk = -1; for (i = 0; i < 24; i++) if (hr[i]) { line = line " " i "=" hr[i]; if (pk < 0 || hr[i] > hr[pk]) pk = i }
print "HOURS:" line; print "PEAK_HOUR: " (pk < 0 ? "n/a" : pk)
bd = ""; bn = 0; for (k in dir) if (dir[k] > bn) { bn = dir[k]; bd = k }
print "FOCUS_SCORE: " (ndf ? int(100 * bn / ndf) : 0) "% (" bd ")"
print "BIGGEST_COMMIT: " big
print "AI_ASSISTED_COMMITS: " aia + 0
print "PR_REFS:" prs
for (k in hot) print "HOTSPOT: " hot[k] " " k | "sort -k2,2nr | head -10"
close("sort -k2,2nr | head -10")
for (i = 1; i <= na; i++) { a = an[i]; print "AUTHOR: " a "|" ac[a] "|+" ai[a] "/-" ad[a] "|tests " (ai[a] ? int(100 * at[a] / ai[a]) : 0) "%|biggest " abs[a] }
}'
# Streaks: consecutive commit days ending at the newest commit (full history, never the clock).
for _W in team user; do
_A=""; [ "$_W" = user ] && _A="--author=$(git config user.email 2>/dev/null || echo none)"
git log "$_REF" ${_A:+"$_A"} --date=format-local:%Y-%m-%d --format=%ad 2>/dev/null | sort -ru | awk -v w="$_W" '
function dn(s, y, m, d) { y = substr(s, 1, 4) + 0; m = substr(s, 6, 2) + 0; d = substr(s, 9, 2) + 0; if (m < 3) { y--; m += 12 }; return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d }
NR == 1 { anchor = $0; prev = dn($0); n = 1; next }
{ if (prev - dn($0) == 1) { n++; prev = dn($0) } else exit }
END { print toupper(w) "_STREAK: " n + 0 " days ending " (anchor ? anchor : "none") }'
done
Line reference:
| Line |
Meaning |
COMMIT: hash|author|date hour|subject |
One per commit, newest first: the raw material for anchoring every claim |
COMMITS / CONTRIBUTORS |
Non-merge commits and distinct authors in the window |
INSERTIONS / DELETIONS / NET_LOC |
Raw LOC, generated output (build/, dist/, node_modules/, ...) excluded |
TEST_INSERTIONS / TEST_RATIO |
Lines added in test files (test dirs, .test. / _spec. suffixes, test_*.py, .bats; prose never counts) |
WEIGHTED_COMMITS |
Commits x files touched, capped at 20 per commit |
ACTIVE_DAYS |
Distinct local dates with commits |
SESSIONS |
45-minute-gap sessions: deep 50+ min, medium 20-50, micro under 20 (usually single-commit) |
TOTAL_ACTIVE_MINUTES / AVG_SESSION_MINUTES / LOC_PER_SESSION_HOUR |
Session time (LOC/hour rounded to the nearest 50) |
COMMIT_TYPES / FIX_RATIO |
Conventional-commit prefixes; ytstack task commits (M###-S##-T##:) count as task |
COMMIT_SIZE_BUCKETS |
small under 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 |
Share of file changes in the busiest top-level directory |
BIGGEST_COMMIT |
Highest-LOC commit (ship-of-the-milestone candidate) |
HOTSPOT: count file |
Ten most-changed files |
AUTHOR: name|commits|+ins/-del|tests N%|biggest ... |
Per-contributor rollup with their biggest commit |
COAUTHOR / AI_ASSISTED_COMMITS |
Human co-author credit; commits with an AI co-author trailer |
PR_REFS |
#NNN references in subjects (not verified merges) |
TEAM_STREAK / USER_STREAK |
Consecutive commit days, anchored at the newest commit date |
Identity: USER_NAME is "you", the person reading the retro. Every other author is a teammate.
Freshness guard. Evaluate in order:
- If
GUARD_REMOTE: none or RETRO_FETCH failed: proceed, and carry "offline run, window not freshness-verified" into the report.
- If the fetch succeeded and
COMMITS: 0 and GUARD_LATEST_COMMIT is older than the window start: stop with "Retro window is stale. Latest commit on <RETRO_REF> is <date>, but the window covers <since> to today. Either today's date is wrong in this session or the base branch is behind. Check the date, run git fetch origin <base>, then run ytstack:retro again."
- If
COMMITS: 0 otherwise: say so, suggest a wider window (ytstack:retro 30d), and continue with summaries only; every git-derived section then reads no commits in window.
- If
BASE_COMMITS_NOT_IN_HEAD is above 0, say once in the report that the branch has not merged the latest base (that many base commits are not counted); the metrics still describe HEAD, which carries the milestone's work.
6. Shipping outcomes
- Merged PRs (only if
HAS_GH=yes): gh pr list --state merged --base "<base>" --search "merged:>=<start-date>" --limit 1000 --json number,title,mergedAt. Filter mergedAt to the exact window, upper bound included in compare mode. At the limit, label the count partial. Without gh, show PRs referenced from PR_REFS and say they are not verified merges.
- Features shipped (only if
CHANGELOG=yes): git log <RETRO_REF> --since "<since>" -p -- CHANGELOG.md (add --until for the prior window). Combine new user-visible capabilities with verified merged PR titles; dedupe entries for the same capability; exclude fixes, chores and reverted work. Keep a short list with the source commit or PR beside each. With neither source: unavailable, not 0.
- Backlog (only if
TODOS=yes): read TODOS.md; count open items (outside a ## Completed section), P0/P1, P2, items completed in the window (dated Completed entries), items added in the window (COMMIT: lines that touched TODOS.md).
7. Analyze
Build each block from the metric lines; anchor every claim in COMMIT: lines or summaries.
Summary table. Lead with what shipped, then volume. Raw LOC is context, not impact.
| Metric |
Value |
| Tasks closed (summaries) |
N of PLAN_TASKS total |
| Features shipped (CHANGELOG + merged PRs) |
N |
Commits to <RETRO_REF> |
N |
| Weighted commits |
N |
| Contributors |
N |
| PRs merged (or referenced) |
N |
| Raw LOC: +ins / -del / net |
N / N / N |
| Test LOC ratio |
N% |
| Active days |
N |
| Sessions (deep / medium / micro) |
N (a / b / c) |
| LOC per session-hour |
N |
| AI-assisted commits |
N of M |
| Backlog (only if TODOS) |
N open (X P0/P1, Y P2), Z completed |
Below it, a per-author leaderboard from AUTHOR: lines, sorted by commits, with the current user first as "You (name)". Solo repo: one line, no team framing.
Time distribution. Render HOURS as a histogram (14: 50 ██████████). Call out peak hours, dead zones, bimodal vs continuous, and late-night clusters (after 22:00).
Sessions. Count and the deep / medium / micro split, total active time, average length, LOC per hour.
Commit types. Render COMMIT_TYPES as a percentage bar. Flag FIX_RATIO above 50%: "ship fast, fix fast" often means review gaps. Look for fix chains (several fixes on the same subsystem in a row).
Hotspots. Files changed 5+ times are churn; tests vs production files in the list; how often VERSION / CHANGELOG appear (release discipline). Cross-check: a churning file that no summary mentions under Deviations is a finding.
Commit sizes. The four buckets and what they say about reviewability.
Focus + ship of the milestone. FOCUS_SCORE with the directory ("Focus: 62% in app/services/"). BIGGEST_COMMIT: PR number if the subject carries one, LOC, and why it matters (from the subject, the files, and the summary that owns it). A vendored-import or generated commit is not a ship; pick the biggest authored one and say why.
People (skip for a solo repo; the retro is personal then). For the current user: sessions, peak hours, focus, biggest ship. For each teammate: 2-3 sentences on what they worked on, 1-2 specific praise points anchored in commits, 1 growth suggestion tied to data. Credit COAUTHOR: humans next to the primary author. AI co-authors are the AI_ASSISTED_COMMITS metric, never a team member; state the share neutrally.
Week-over-week (only if the window is 14 days or longer). Group COMMIT: lines by week (newest week first): commits per week, per author, and fix ratio per week. For LOC and test ratio per week, re-run the step 5 command with one <since> / <until> pair per week.
Streaks. Interpret TEAM_STREAK / USER_STREAK against today: anchor today or yesterday = live streak; older = broken, report 0 days and the last commit day.
8. Milestone outcomes
This is the part a calendar retro cannot give. From the material read in step 3:
Exit criteria. One line per criterion in M###-CONTEXT.md: met / partly / not met, each with the summary or commit that proves it.
Plan completion. PLAN_TASKS done vs total, per slice; name any open task.
Verification. Count summaries by verification: value (passed, passed_with_caveats, failed); list each caveat in one line.
Deviations. Every non-empty Deviations section, grouped by cause (plan was wrong, scope grew, tool or environment surprise, upstream change). Repeated causes are the strongest lesson candidates.
Follow-ups. Every follow-up from the summaries, marked done (a later commit or summary resolves it) or open. Open follow-ups are candidates for the next milestone, not for silent dropping.
Summaries vs git. Where the two witnesses disagree (a "clean" task next to a fix chain, a task with no commits in the window, commits with no task), say so plainly.
Own reviewers vs bots (only if OWN_REVIEWERS is not none). Read from the signals ledger, never from the host. The counts come from .ytstack/signals/review-checks (format: docs/ux/signal-format.md, "Review escapes"): one line per checked merged pull request, <owner/name>#<n> <merge sha> <check time> [<tally>], the tally <role>=<caught>/<escaped> comma separated, or none. Take the lines whose check time lies in the window and sum caught and escaped per role; the escape rate of a role is escaped / (caught + escaped), n/a at 0. - collects escapes no role owns: show it as its own row, it is a gap in the roles. A line without a tally was written before tallies existed: list those pull requests as "not recorded" and leave them out of the sums, never count them as 0. The classes come from the findings between REVIEW_FINDINGS_BEGIN and REVIEW_FINDINGS_END: per role the keys and their state. One row per role of OWN_REVIEWERS, a role without findings included:
| Role |
Caught |
Escaped |
Escape rate |
Classes (open / planned / fixed / dismissed) |
Proposed (ref a question) |
Above the table: how many checked pull requests the window has, how many of them without a tally, and how many merged pull requests step 6 found, when it found any; a gap means pull requests had no escape check. A class whose count is 2 or more and that is still open without a question is a candidate for "3 Things to Improve". Put the table under ## Milestone Outcomes and "review_escapes": {"<role>": {"caught": <n>, "escaped": <n>}, ...} into the snapshot.
Incidents and lessons (only if LESSONS is above 0). Read from the signals ledger (docs/ux/signal-format.md, "Lessons"): every incident of any class left a sighting on the lesson of its class. Run, with the window start of step 4 as a UTC time:
bash "<SIGNALS_TOOL>" lesson list --state all --since <since, e.g. 2026-11-01T00:00:00Z>
One line per lesson: id, state, area, class, count, sightings in the window, target, ref, reopens, title. Show the lessons with at least one sighting in the window, grouped by area, one row per class:
| Area |
Class |
Incidents in window |
All time |
Repeat |
Where the lesson lives |
State |
Repeat is yes when the class counts 2 or more, or when the lesson reopens an earlier one (reopens is not none: the lesson that was in place did not hold). Above the table: the incidents in the window per area, and how many classes repeated. Only the newest five sightings of a class stay in its file, so a class with more in the window says "at least 5". A repeated class whose lesson is still a proposal or only a knowledge entry is a candidate for "3 Things to Improve" (name its id), and a reopened one is always one. Put "lessons": {"incidents": <n>, "classes": <n>, "repeats": <n>, "open": <n>} into the snapshot.
9. Compare with the prior retro
Only if PRIOR_RETRO is not none, or in compare mode.
- Trends. From the prior retro's
## Snapshot JSON (or, in compare mode, the prior-window metrics), show a Trends table: test ratio, sessions, deep sessions, LOC per hour, fix ratio, commits, tasks per active day. Ratio changes in percentage points; a zero prior value gives n/a for the percentage. Prior milestones differ in length, so say so when the windows differ by more than 2x and prefer per-day rates.
- Recommendation follow-through. Score each prior
recommendations item as addressed, partial or open against this window's commits, changed files and summaries, citing the evidence. One headline ("2 of 3 prior recommendations addressed"), then one line per item. Skip silently when the snapshot has no recommendations key.
- No prior retro and no
compare: append "First retro recorded; the next milestone's retro will show trends."
10. Ask before replacing
Only if RETRO_EXISTS=yes. Check git status --short -- <RETRO_FILE> first; an uncommitted file would be lost on replace, so say so in the question.
In YTSTACK_NON_INTERACTIVE: true mode, auto-pick A and log: "[ytstack:retro] auto-picked A (replace) because YTSTACK_NON_INTERACTIVE=true".
Otherwise use AskUserQuestion:
I'm writing the retro for <MILESTONE> of <PROJECT_SLUG> on branch <BRANCH>, and <RETRO_FILE> already exists (<committed / has uncommitted changes>).
A retro for this milestone was written before. Replacing it keeps the old version in git history if it was committed; if it has uncommitted edits, those are gone. Keeping it means this run ends without writing anything.
RECOMMENDATION: Choose A because the new retro covers the milestone's final state and the old one stays recoverable in git.
A) Replace the file with the new retro
Completeness: 10/10, effort: human: 0 / CC: ~1 min, tier: task
B) Keep the existing file and stop
Completeness: 3/10, effort: human: 0 / CC: 0, tier: task
If B: show the report in the conversation only, skip steps 11 and 12, and report "kept existing <RETRO_FILE>".
11. Write M###-RETRO.md
Draft the one-line summary and the "3 Things to Improve" first; the snapshot reuses them verbatim. Write RETRO_FILE with the Write tool:
---
milestone: <MILESTONE>
project: <PROJECT_SLUG>
created: <ISO-8601 UTC timestamp>
---
# <MILESTONE> -- Retro
<one-line summary: "M016 (Nov 1-7): 14 tasks, 132 commits, 26% tests, 3 PRs, peak 14:00, 1 deviation pattern">
## Summary
<summary table + leaderboard from step 7>
## Milestone Outcomes
<exit criteria, plan completion, verification, deviations, follow-ups, summaries vs git from step 8>
## Trends vs Last Retro
<step 9 table + recommendation follow-through; or the first-retro line; in compare mode "Current vs Prior Window">
## Time & Session Patterns
<histogram + narrative: when the productive hours are, session length, estimated active hours per day, whether people work in parallel or in shifts>
## Shipping Velocity
<commit types, size buckets, fix chains, release discipline>
## Code Quality Signals
<test ratio and trend, hotspots, churn without a matching deviation>
## Focus & Highlights
<focus score, ship of the milestone>
## Streaks
<team + personal, broken-streak disclosure>
## Your Milestone
<personal deep-dive for USER_NAME: commits, LOC, test ratio, sessions, peak hours, focus, biggest ship; **What you did well** (2-3, anchored in commits); **Where to level up** (1-2, actionable)>
## Team Breakdown
<per teammate, sorted by commits: what they shipped, praise, one growth opportunity; omit the section for a solo repo>
## Top 3 Wins
<what, who, why it matters for the product or architecture>
## 3 Things to Improve
<specific, actionable, each naming a concrete file, script or check, so the next retro can score it>
## 3 Habits for the Next Milestone
<each adoptable in under 5 minutes; at least one team-oriented when there is a team>
## Upstream
<filled in step 13: what of this milestone concerns ytstack itself, and what happened to it>
## Snapshot
```json
{ "milestone": "M016", "window": "2026-11-01..2026-11-07", "metrics": { "commits": 132, "contributors": 1, "prs_merged": null, "insertions": 33620, "deletions": 8431, "test_ratio": 0.26, "active_days": 1, "sessions": 1, "deep_sessions": 1, "loc_per_session_hour": 7400, "fix_pct": 0.01, "peak_hour": 14, "ai_assisted_commits": 7, "tasks_done": 14, "tasks_total": 14 }, "streak_days": 1, "summary": "<the one-line summary>", "recommendations": [ { "category": "testing", "text": "<item 1 verbatim>" } ] }
```
Rules for the file:
- Size every section to its evidence. A section with nothing to say is cut, not padded. Keep
## Summary, ## Milestone Outcomes, ## 3 Things to Improve, ## Upstream and ## Snapshot always.
prs_merged is null when hosting data was unavailable. recommendations is always present: one object per "3 Things to Improve" item with a one-word lowercase category and the item text verbatim; [] when there are none, never padded.
- Add
"backlog": {...} only when TODOS=yes, "review_escapes": {...} only when OWN_REVIEWERS is not none, and "lessons": {...} only when LESSONS is above 0.
- After writing, show the report (everything above
## Snapshot) in the conversation.
Tone. Encouraging but candid, no coddling. Specific and concrete, always anchored in commits or summaries. No generic praise ("great job"): say what was good and why. Praise sounds like something you would say in a 1:1. Growth suggestions sound like investment advice ("worth your time because..."), not "you failed at". Never compare teammates against each other negatively. Tables and code blocks for data, prose for narrative. If the test ratio is under 20%, flag it as a growth area.
12. Propose lessons
From the deviations, follow-ups, summaries-vs-git disagreements and the "3 Things to Improve", draft:
- KNOWLEDGE entries: patterns, pitfalls, gotchas that would save a future session 5+ minutes. One bullet each, in the style of the existing
KNOWLEDGE.md sections (bold lead, one or two sentences, a concrete file or command).
- DECISIONS entries: only choices made during the milestone that outlive it and are not yet in
DECISIONS.md. Use the file's own entry format (## YYYY-MM-DD: <title> with Context / Options considered / Chose / Reason).
Skip anything obvious, anything already in either file (grep first), and one-off transient errors. If nothing qualifies, say "No durable lessons this milestone" and skip the question.
Show the drafted entries as a numbered list. In YTSTACK_NON_INTERACTIVE: true mode, auto-pick A and log: "[ytstack:retro] auto-picked A (write all) because YTSTACK_NON_INTERACTIVE=true". Otherwise use AskUserQuestion:
The <MILESTONE> retro for <PROJECT_SLUG> on branch <BRANCH> is written to <RETRO_FILE>. I drafted KNOWLEDGE and DECISIONS entries (listed above).
These files are the project's long-term memory: every future session reads them, so a lesson written there stops the same mistake from happening twice. A lesson that stays only in the retro is read once and forgotten.
RECOMMENDATION: Choose A because every entry is drafted from evidence in this milestone and none duplicates an existing one.
A) Write all drafted entries
Completeness: 10/10, effort: human: 0 / CC: ~1 min, tier: task
B) Let me pick entry by entry
Completeness: 8/10, effort: human: ~2 min / CC: ~1 min, tier: task
C) Write none, keep the lessons in the retro only
Completeness: 4/10, effort: human: 0 / CC: 0, tier: task
- A: append every entry (KNOWLEDGE under the fitting section, DECISIONS at the end, never rewriting past entries).
- B: ask one yes/no question per entry, in order, each re-grounded with the entry text; write the yes entries.
- C: write nothing.
Then add a ## Lessons recorded line to RETRO_FILE (before ## Upstream) naming what went where.
13. Upstream
The project's lessons went into its own files in step 12. This step is about ytstack itself: a skill, hook or script of the plugin that misled, failed or was missing, a workaround built around one, a ytstack tool that ran against a real host for the first time. The channel and its rules: ${CLAUDE_SKILL_DIR}/../../docs/ux/upstream-feedback.md; read its "The steps" and "The rules" before acting.
From the material of steps 3 to 8 (deviations caused by a tool surprise, workarounds in summaries, follow-ups and "3 Things to Improve" that name a ytstack skill or script), list the observations that concern ytstack, one per line with its kind (bug, gap, proposal, evidence) and the evidence (summary, commit, count). Nothing qualifies, or the project is ytstack itself (its own artifacts are the place): write "Nothing this milestone concerns ytstack itself." under ## Upstream and go on. Otherwise, by UPSTREAM_FEEDBACK:
off: write upstream_feedback: off and the list under ## Upstream, send nothing, suggest nothing.
suggest or unavailable: per observation, search, draft with "<UPSTREAM_TOOL>" draft, fill it, run check until draft ok. Send nothing. Each line under ## Upstream ends with suggested: <draft path> (and matches #<n> when the search found the same behaviour).
file: per observation, search, draft, fill, check, then gh issue create or, for a match, gh issue comment, as the document says. Each line ends with filed #<n> or commented #<n>. A draft that does not pass check is not sent: the line ends with not sent: <the check's line>.
In YTSTACK_NON_INTERACTIVE: true mode nothing is sent under any setting: the lines end with suggested: <draft path> and the report lists them under "Waiting on a person".
14. Re
…(truncated)
1---2name: retro3description: "Milestone retrospective fed with the milestone's task summaries, deviations and follow-ups plus the git history of the milestone window, written to M###-RETRO.md. Use after a milestone's last slice closed and reassess-roadmap ran, or when the user says retro, retrospective, what did we learn, lessons from this milestone. Not mid-milestone (reassess-roadmap) and not for closing a task (summarize-task)."4metadata:5 source: https://skillmd.com/skills/yesterday-ai/retro6 tier: task7 version: 1.3.08 upstream: "gstack v1.99.3.0 (retro/, commit 1d3c63c53)"9allowed-tools:10 - Bash11 - Read12 - Write13 - Edit14 - AskUserQuestion15---1617# ytstack:retro1819Adapted from gstack's `retro` skill (MIT, Garry Tan), baseline in `metadata.upstream`; see NOTICE.2021A milestone retrospective with two kinds of evidence: what the task summaries say happened (outcome, deviations, follow-ups, verification) and what git says happened (commits, sessions, hotspots, test share, shipping pace). The result is `M###-RETRO.md` next to the milestone, plus lessons copied into `KNOWLEDGE.md` and `DECISIONS.md` with the user's consent. Differs from upstream: scoped to a milestone instead of a calendar week, history lives in prior `M###-RETRO.md` files, no global cross-project mode.2223<HARD-GATE>24Do NOT write `M###-RETRO.md`, append to `KNOWLEDGE.md` or `DECISIONS.md`, or report a single metric until `HAS_YTSTACK` is `yes`, `MILESTONE` is not `none`, `SUMMARIES` is above 0, and the metrics command below has actually run. Never invent a number: a metric you could not compute is written as `unavailable`, never as 0.25This applies to EVERY milestone regardless of how small or obvious it looks.26</HARD-GATE>2728## Anti-Pattern: "The summaries already say what happened, skip the git data"2930Summaries are written by the agent that did the work, right after it did it. They describe intent and outcome; they do not show that one file churned 14 times, that 60% of the commits were fixes, or that every session ran past midnight. Git is the second witness. A retro built from summaries alone repeats what everyone already believes. Run the metrics, then let the two sources argue with each other: a summary that says "clean" next to a fix chain on the same file is the finding.3132## Checklist3334You MUST create a task for each of these items and complete them in order:35361. **Run preamble** -- resolver, milestone, summary count, window anchors, base branch, prior retro372. **HARD-GATE** -- stop without a milestone or without summaries383. **Read the material** -- every `M###-S##-T##-SUMMARY.md`, `M###-CONTEXT.md`, `M###-ROADMAP.md`, the slice plans, `PRIOR_RETRO`394. **Fix the window** -- milestone window by default, or the user's `<N>d|h|w` / `compare` argument405. **Gather metrics** -- one bash command, then the freshness guard416. **Shipping outcomes** -- merged PRs (only if `HAS_GH=yes`), CHANGELOG features, backlog (only if `TODOS=yes`)427. **Analyze** -- time, sessions, commit types, hotspots, sizes, focus, ship of the milestone, people, streaks438. **Milestone outcomes** -- exit criteria vs summaries, deviations, open follow-ups, plan completion; own reviewers vs bots (only if `OWN_REVIEWERS` is not `none`); incidents and repeats per class (only if `LESSONS` is above 0)449. **Compare with the prior retro** (only if `PRIOR_RETRO` is not `none`, or in `compare` mode) -- trends + recommendation follow-through4510. **Ask before replacing** (only if `RETRO_EXISTS=yes`) -- replace or stop4611. **Write `M###-RETRO.md`** -- frontmatter + report + snapshot, and show the report in the conversation4712. **Propose lessons** -- KNOWLEDGE / DECISIONS entries, ask once, write what the user accepts4813. **Upstream** -- what of this milestone concerns ytstack itself, handled per `UPSTREAM_FEEDBACK`, recorded under `## Upstream`4914. **Report + return** -- paths, entry counts, upstream lines, next-step suggestion, no auto-chaining5051## Process Flow5253```dot54digraph retro {55 "Start" [shape=doublecircle];56 "Milestone + summaries?" [shape=diamond];57 "Stop: nothing to review" [shape=doublecircle];58 "Read summaries + context" [shape=box];59 "Window + metrics" [shape=box];60 "Window stale?" [shape=diamond];61 "Stop: fix date or fetch" [shape=doublecircle];62 "Analyze + milestone outcomes" [shape=box];63 "Compare with prior retro" [shape=box];64 "RETRO exists?" [shape=diamond];65 "Write M###-RETRO.md" [shape=box];66 "Ask: lessons" [shape=diamond];67 "Upstream per setting" [shape=box];68 "Report" [shape=doublecircle];6970 "Start" -> "Milestone + summaries?";71 "Milestone + summaries?" -> "Stop: nothing to review" [label="no"];72 "Milestone + summaries?" -> "Read summaries + context" [label="yes"];73 "Read summaries + context" -> "Window + metrics";74 "Window + metrics" -> "Window stale?";75 "Window stale?" -> "Stop: fix date or fetch" [label="yes"];76 "Window stale?" -> "Analyze + milestone outcomes" [label="no"];77 "Analyze + milestone outcomes" -> "Compare with prior retro";78 "Compare with prior retro" -> "RETRO exists?";79 "RETRO exists?" -> "Write M###-RETRO.md" [label="no / replace"];80 "RETRO exists?" -> "Report" [label="keep"];81 "Write M###-RETRO.md" -> "Ask: lessons";82 "Ask: lessons" -> "Upstream per setting";83 "Upstream per setting" -> "Report";84}85```8687## Preamble8889Resolved when the skill loads:9091```!92# ytstack resolver (M016): checkout = where this shell runs, via the shared lib.93_LIB="${CLAUDE_SKILL_DIR}/../../hooks/lib/git-ctx.sh"94if [ -f "$_LIB" ]; then95 . "$_LIB"; yt_git_ctx "$PWD"; yt_resolve_yt_dir >/dev/null96 _PROJECT_DIR="$YT_TOPLEVEL"; _YT_DIR="$YT_DIR"; _YT_SCOPE="$YT_SCOPE"; _IS_GIT="$YT_IS_GIT"; _PROJECT_KEY="$YT_REPO_KEY"97else98 # Host did not substitute CLAUDE_SKILL_DIR (e.g. Codex adapter): project scope only.99 _IS_GIT=$([ "$(git rev-parse --is-inside-work-tree 2>/dev/null)" = true ] && echo yes || echo no)100 _PROJECT_DIR=$(git rev-parse --show-toplevel 2>/dev/null || pwd -P)101 _YT_DIR=""; _YT_SCOPE=none; _PROJECT_KEY=""102 [ -d "$_PROJECT_DIR/.ytstack" ] && { _YT_DIR="$_PROJECT_DIR/.ytstack"; _YT_SCOPE=project; }103fi104cd "$_PROJECT_DIR" 2>/dev/null || true105_PROJECT_SLUG=$(basename "$_PROJECT_DIR") # display only106_HAS_YTSTACK=$([ -n "$_YT_DIR" ] && echo yes || echo no)107echo "BRANCH: $(git branch --show-current 2>/dev/null || echo unknown)"108echo "PROJECT_SLUG: $_PROJECT_SLUG"109echo "HAS_YTSTACK: $_HAS_YTSTACK"110echo "YTSTACK_SCOPE: $_YT_SCOPE"111echo "YT_DIR: $_YT_DIR"112if [ -n "$YTSTACK_NON_INTERACTIVE" ] || [ -n "$OPENCLAW_SESSION" ] || [ -n "$CLAUDE_AGENT_TEAM_MEMBER" ]; then113 echo "YTSTACK_NON_INTERACTIVE: true"114else115 echo "YTSTACK_NON_INTERACTIVE: false"116fi117if [ -f "$_YT_DIR/STATE.md" ]; then118 echo "CURRENT_MILESTONE: $(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1)"119 echo "ACTIVE_SLICE: $(sed -n 's/^active_slice: *//p' "$_YT_DIR/STATE.md" | head -1)"120fi121# Milestone to review: the current one.122_M=none; _SUMMARIES=0; _RETRO_FILE=none; _PRIOR=none; _FIRST=none; _CREATED=none; _TASKS_DONE=0; _TASKS_ALL=0123if [ -n "$_YT_DIR" ] && [ -f "$_YT_DIR/STATE.md" ]; then124 _M=$(sed -n 's/^current_milestone: *//p' "$_YT_DIR/STATE.md" | head -1); _M=${_M:-none}125 if [ "$_M" != none ]; then126 _SUMMARIES=$(ls "$_YT_DIR"/$_M-S[0-9][0-9]-T[0-9][0-9]-SUMMARY.md 2>/dev/null | grep -c .)127 _RETRO_FILE="$_YT_DIR/$_M-RETRO.md"128 _PRIOR=$(ls "$_YT_DIR"/M[0-9][0-9][0-9]-RETRO.md 2>/dev/null | grep -v "/$_M-RETRO.md" | sort | tail -1); _PRIOR=${_PRIOR:-none}129 [ -f "$_YT_DIR/$_M-CONTEXT.md" ] && _CREATED=$(sed -n 's/^created: *//p' "$_YT_DIR/$_M-CONTEXT.md" | head -1 | cut -c1-10)130 _CREATED=${_CREATED:-none}131 if command -v yt_commit_ref_pattern >/dev/null 2>&1; then132 _PAT=$(yt_commit_ref_pattern "$_YT_DIR" "$_M" 'S[0-9][0-9]' 'T[0-9][0-9]')133 else134 _PAT="^$_M-S[0-9][0-9]-T[0-9][0-9]:"135 fi136 _FIRST=$(git log --no-merges -E --grep "$_PAT" --date=format-local:%Y-%m-%d --format=%ad 2>/dev/null | tail -1); _FIRST=${_FIRST:-none}137 _TASKS_DONE=$(cat "$_YT_DIR"/$_M-S[0-9][0-9]-PLAN.md 2>/dev/null | grep -cE '^- \[[xX]\] T[0-9][0-9]')138 _TASKS_ALL=$(cat "$_YT_DIR"/$_M-S[0-9][0-9]-PLAN.md 2>/dev/null | grep -cE '^- \[[ xX]\] T[0-9][0-9]')139 fi140fi141_BASE=$(git symbolic-ref --quiet refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')142for _C in main master; do [ -n "$_BASE" ] && break; git rev-parse --verify --quiet "$_C" >/dev/null 2>&1 && _BASE=$_C; done143echo "MILESTONE: $_M"144echo "SUMMARIES: $_SUMMARIES"145echo "RETRO_FILE: $_RETRO_FILE"146echo "RETRO_EXISTS: $([ -f "$_RETRO_FILE" ] && echo yes || echo no)"147echo "PRIOR_RETRO: $_PRIOR"148echo "FIRST_TASK_COMMIT: $_FIRST"149echo "CONTEXT_CREATED: $_CREATED"150echo "PLAN_TASKS: $_TASKS_DONE/$_TASKS_ALL done"151echo "BASE_BRANCH: ${_BASE:-$(git branch --show-current 2>/dev/null)}"152echo "USER_NAME: $(git config user.name 2>/dev/null || echo unknown)"153echo "HAS_GH: $(command -v gh >/dev/null 2>&1 && gh auth status >/dev/null 2>&1 && echo yes || echo no)"154echo "CHANGELOG: $([ -f "$_PROJECT_DIR/CHANGELOG.md" ] && echo yes || echo no)"155echo "TODOS: $([ -f "$_PROJECT_DIR/TODOS.md" ] && echo yes || echo no)"156# Own reviewers (M030): the roles of REVIEW.md and the escape records of the signals ledger.157_RISK="${CLAUDE_SKILL_DIR}/../../bin/ytstack-risk"; [ -f "$_RISK" ] || _RISK=$(command -v ytstack-risk 2>/dev/null)158_SIG="${CLAUDE_SKILL_DIR}/../../bin/ytstack-signals"; [ -f "$_SIG" ] || _SIG=$(command -v ytstack-signals 2>/dev/null)159_ROLES=""; [ -n "$_RISK" ] && _ROLES=$(bash "$_RISK" -C "$_PROJECT_DIR" reviewers 2>/dev/null | cut -f1 | tr '\n' ' ')160echo "OWN_REVIEWERS: ${_ROLES:-none}"161if [ -n "$_ROLES" ] && [ -n "$_SIG" ]; then162 echo "REVIEW_FINDINGS_BEGIN"163 bash "$_SIG" -C "$_PROJECT_DIR" list --state all 2>/dev/null | awk -F'\t' '$4 == "review"'164 echo "REVIEW_FINDINGS_END"165fi166# Lessons (M032): every incident of any class left one in the signals ledger; step 8 counts them per class for the window.167echo "LESSONS: $([ -n "$_SIG" ] && [ -n "$_YT_DIR" ] && bash "$_SIG" -C "$_PROJECT_DIR" lesson list --state all 2>/dev/null | awk 'NF { n++ } END { print n + 0 }' || echo 0)"168echo "SIGNALS_TOOL: ${_SIG:-unavailable}"169# Upstream feedback (M033): the effective setting; the rules are docs/ux/upstream-feedback.md.170_UP="${CLAUDE_SKILL_DIR}/../../bin/ytstack-upstream"; [ -f "$_UP" ] || _UP=$(command -v ytstack-upstream 2>/dev/null)171_UPM=""; [ -n "$_UP" ] && _UPM=$(bash "$_UP" -C "$_PROJECT_DIR" mode 2>/dev/null | sed -n 's/^mode: //p')172echo "UPSTREAM_FEEDBACK: ${_UPM:-unavailable}"173echo "UPSTREAM_TOOL: ${_UP:-unavailable}"174```175176## Procedure177178**Today** is the date in the session context (`currentDate`), never the output of `date`: the system clock in a container can be hours off. If the session carries no date, ask the user for today's date in one short open question (re-ground: project, branch, "I need today's date to set the retro window") and wait. In `YTSTACK_NON_INTERACTIVE: true` mode, stop with "no reliable date; pass today's date in the brief" instead.179180All times are the user's local timezone. Never set `TZ`.181182### 1. Run preamble183184The preamble above ran when the skill loaded. Read its flags; refer to them by name below.185186### 2. HARD-GATE1871881. If `HAS_YTSTACK` is `no` or `MILESTONE` is `none`: stop with "no milestone to review; run `ytstack:resume-session`".1892. If `SUMMARIES` is `0`: stop with "the milestone has no task summaries yet; retro runs after the last `ytstack:summarize-task`".1903. Otherwise continue. If `PLAN_TASKS` shows open tasks (done below total), say once that the retro covers a milestone with unfinished tasks and name them in the Milestone Outcomes section; do not stop.191192### 3. Read the material193194Read, with the Read tool, in this order: `<YT_DIR>/<MILESTONE>-CONTEXT.md` (goal, exit criteria, decisions locked during discuss), `<YT_DIR>/<MILESTONE>-ROADMAP.md`, every `<YT_DIR>/<MILESTONE>-S##-PLAN.md`, every `<YT_DIR>/<MILESTONE>-S##-T##-SUMMARY.md` (Commits, Outcome, Deviations, Follow-ups, Verification and the `verification:` frontmatter key), and `PRIOR_RETRO` when it is not `none` (its `## Snapshot` block holds the metrics and recommendations to compare against).195196Do not read unrelated docs. `CHANGELOG.md` and `TODOS.md` are read in step 6, nothing else outside `.ytstack/`.197198### 4. Fix the window199200Default: the **milestone window**. Start = `FIRST_TASK_COMMIT`, else `CONTEXT_CREATED`, else 14 days before today. End = now. Align the start to local midnight: `--since "<start>T00:00:00"` (without the `T00:00:00` suffix git uses the current wall-clock time of that day).201202The user may override with an argument:203204- `<N>d` / `<N>w` -- the last N days (weeks x 7), midnight-aligned.205- `<N>h` -- `--since "<N> hours ago"`, no midnight alignment.206- `compare` or `compare <N>d` -- the window (milestone window by default) plus the immediately prior window of the same length. The prior window ends one second before the current start (`--until "<day before start>T23:59:59"`), because git includes the `--until` boundary and a commit must not count twice.207208Any other argument: show this usage and stop.209210```text211Usage: ytstack:retro [window | compare [window]]212 ytstack:retro -- the milestone window (first task commit .. now)213 ytstack:retro 14d -- last 14 days instead214 ytstack:retro 24h -- last 24 hours215 ytstack:retro compare -- milestone window vs the prior window of the same length216```217218Say the window in one line before running the metrics: "Window: 2026-11-01 .. today (milestone M016, from the first task commit)".219220### 5. Gather metrics221222Run this once. Substitute `<since>` (for example `2026-11-01T00:00:00`), `<until>` (empty for the current window) and `<base>` (`BASE_BRANCH`). In `compare` mode run it a second time for the prior window with both `<since>` and `<until>` set, and keep the two outputs apart.223224```bash225_SINCE="<since>"; _UNTIL="<until>"; _BASE="<base>"226# Freshness: refresh the base ref; offline or no remote is fine, the guard discloses it.227git fetch origin "$_BASE" --quiet 2>/dev/null && echo "RETRO_FETCH: ok" || echo "RETRO_FETCH: failed (offline or no remote)"228# Analyzed ref: always HEAD, so the milestone's own commits are counted even229# before the branch has merged the latest base. Divergence is only reported.230_REF=HEAD; _BEHIND=0231for _C in "origin/$_BASE" "$_BASE"; do232 git rev-parse --verify --quiet "$_C" >/dev/null 2>&1 || continue233 _BEHIND=$(git rev-list --count "HEAD..$_C" 2>/dev/null || echo 0)234 break235done236echo "RETRO_REF: $_REF"237echo "BASE_COMMITS_NOT_IN_HEAD: $_BEHIND"238echo "GUARD_REMOTE: $(git remote 2>/dev/null | grep -qx origin && echo origin || echo none)"239echo "GUARD_LATEST_COMMIT: $(git log -1 --date=format-local:%Y-%m-%d --format=%ad "$_REF" 2>/dev/null || echo unknown)"240echo "WINDOW: $_SINCE .. ${_UNTIL:-now}"241# One numstat walk over the window -> every per-commit metric.242git log "$_REF" --no-merges --since="$_SINCE" ${_UNTIL:+--until="$_UNTIL"} \243 --date=format-local:'%Y-%m-%d %H' --numstat \244 --format='C|%h|%aN|%at|%ad|%(trailers:key=Co-authored-by,valueonly,separator=;)|%s' 2>/dev/null | awk -F'\t' '245function gen(p) { return p ~ /(^|\/)(build|dist|out|target|vendor|node_modules|\.next|coverage|__pycache__)\// }246function prose(p) { return p ~ /\.(md|mdx|txt|rst|adoc)$/ || p ~ /(^|\/)docs?\// }247function istest(p) { return !prose(p) && (p ~ /(^|\/)(tests?|specs?|__tests__)\// || p ~ /(\.|_)(test|spec)\./ || p ~ /(^|\/)test_[^\/]*\.(py|rb)$/ || p ~ /\.bats$/) }248function endsess() { L = (last - first) / 60; tot += L; if (L >= 50) deep++; else if (L >= 20) med++; else mic++ }249function flush() {250 if (h == "") return251 loc = ci + cd; nc++; ins += ci; del += cd; tins += ti252 ai[a] += ci; ad[a] += cd; at[a] += ti253 if (loc < 100) b1++; else if (loc < 500) b2++; else if (loc < 1500) b3++; else b4++254 if (loc > bigloc) { bigloc = loc; big = h " " loc " LOC -- " s }255 if (loc > abig[a]) { abig[a] = loc; abs[a] = h " " loc " LOC -- " s }256 wc += (cf > 20 ? 20 : cf)257}258/^C\|/ {259 flush(); n = split($0, f, "|"); h = f[2]; a = f[3]; ep[++ne] = f[4]260 s = f[7]; for (i = 8; i <= n; i++) s = s "|" f[i]261 split(f[5], dh, " "); day[dh[1]] = 1; hr[dh[2] + 0]++262 ac[a]++; if (!(a in seen)) { seen[a] = 1; na++; an[na] = a }263 if (f[6] ~ /noreply@anthropic\.com|[Cc]laude|[Cc]opilot|[Cc]odex|[Cc]ursor/) aia++264 nco = split(f[6], co, ";"); for (i = 1; i <= nco; i++) if (co[i] != "" && co[i] !~ /noreply@anthropic\.com|[Cc]laude|[Cc]opilot|[Cc]odex|[Cc]ursor/) print "COAUTHOR: " h "|" co[i]265 t = "other"266 if (s ~ /^M[0-9][0-9][0-9]-S[0-9][0-9]-T[0-9][0-9]:/) t = "task"267 else if (match(s, /^[a-z]+(\([^)]*\))?!?:/)) { t = substr(s, 1, RLENGTH); sub(/[(!:].*/, "", t) }268 ty[t]++; if (!(t in tseen)) { tseen[t] = 1; nt++; tn[nt] = t }269 while (match(s, /#[0-9]+/)) { prs = prs " " substr(s, RSTART, RLENGTH); s = substr(s, RSTART + RLENGTH) }270 s = f[7]; for (i = 8; i <= n; i++) s = s "|" f[i]271 print "COMMIT: " h "|" a "|" f[5] ":00|" s272 ci = 0; cd = 0; ti = 0; cf = 0; next273}274NF >= 3 && $1 != "" {275 p = $3; if (gen(p)) next276 x = ($1 == "-" ? 0 : $1); y = ($2 == "-" ? 0 : $2)277 ci += x; cd += y; cf++; hot[p]++278 if (istest(p)) ti += x279 d = p; sub(/\/.*/, "/", d); if (d == p) d = "(root)"; dir[d]++; ndf++280}281END {282 flush()283 print "COMMITS: " nc + 0; print "CONTRIBUTORS: " na + 0284 print "INSERTIONS: " ins + 0; print "DELETIONS: " del + 0; print "NET_LOC: " ins - del285 print "TEST_INSERTIONS: " tins + 0; print "TEST_RATIO: " (ins ? int(100 * tins / ins) : 0) "%"286 print "WEIGHTED_COMMITS: " wc + 0287 nd = 0; for (k in day) nd++; print "ACTIVE_DAYS: " nd288 # Sessions: a gap of more than 45 minutes between commits starts a new one (log is newest first).289 ns = 0; deep = 0; med = 0; mic = 0; tot = 0290 for (i = ne; i >= 1; i--) {291 if (i < ne && ep[i] - ep[i + 1] > 2700) endsess()292 if (i == ne || ep[i] - ep[i + 1] > 2700) { ns++; first = ep[i] }293 last = ep[i]294 }295 if (ne) endsess()296 print "SESSIONS: " ns " (deep " deep + 0 ", medium " med + 0 ", micro " mic + 0 ")"297 print "TOTAL_ACTIVE_MINUTES: " int(tot); print "AVG_SESSION_MINUTES: " (ns ? int(tot / ns) : 0)298 print "LOC_PER_SESSION_HOUR: " (tot > 0 ? int(ins / (tot / 60) / 50 + 0.5) * 50 : "n/a")299 line = ""; for (i = 1; i <= nt; i++) line = line " " tn[i] "=" ty[tn[i]]; print "COMMIT_TYPES:" line300 print "FIX_RATIO: " (nc ? int(100 * ty["fix"] / nc) : 0) "%"301 print "COMMIT_SIZE_BUCKETS: small=" b1 + 0 " medium=" b2 + 0 " large=" b3 + 0 " xl=" b4 + 0302 line = ""; pk = -1; for (i = 0; i < 24; i++) if (hr[i]) { line = line " " i "=" hr[i]; if (pk < 0 || hr[i] > hr[pk]) pk = i }303 print "HOURS:" line; print "PEAK_HOUR: " (pk < 0 ? "n/a" : pk)304 bd = ""; bn = 0; for (k in dir) if (dir[k] > bn) { bn = dir[k]; bd = k }305 print "FOCUS_SCORE: " (ndf ? int(100 * bn / ndf) : 0) "% (" bd ")"306 print "BIGGEST_COMMIT: " big307 print "AI_ASSISTED_COMMITS: " aia + 0308 print "PR_REFS:" prs309 for (k in hot) print "HOTSPOT: " hot[k] " " k | "sort -k2,2nr | head -10"310 close("sort -k2,2nr | head -10")311 for (i = 1; i <= na; i++) { a = an[i]; print "AUTHOR: " a "|" ac[a] "|+" ai[a] "/-" ad[a] "|tests " (ai[a] ? int(100 * at[a] / ai[a]) : 0) "%|biggest " abs[a] }312}'313# Streaks: consecutive commit days ending at the newest commit (full history, never the clock).314for _W in team user; do315 _A=""; [ "$_W" = user ] && _A="--author=$(git config user.email 2>/dev/null || echo none)"316 git log "$_REF" ${_A:+"$_A"} --date=format-local:%Y-%m-%d --format=%ad 2>/dev/null | sort -ru | awk -v w="$_W" '317 function dn(s, y, m, d) { y = substr(s, 1, 4) + 0; m = substr(s, 6, 2) + 0; d = substr(s, 9, 2) + 0; if (m < 3) { y--; m += 12 }; return 365 * y + int(y / 4) - int(y / 100) + int(y / 400) + int((153 * (m - 3) + 2) / 5) + d }318 NR == 1 { anchor = $0; prev = dn($0); n = 1; next }319 { if (prev - dn($0) == 1) { n++; prev = dn($0) } else exit }320 END { print toupper(w) "_STREAK: " n + 0 " days ending " (anchor ? anchor : "none") }'321done322```323324**Line reference:**325326| Line | Meaning |327| --- | --- |328| `COMMIT: hash\|author\|date hour\|subject` | One per commit, newest first: the raw material for anchoring every claim |329| `COMMITS` / `CONTRIBUTORS` | Non-merge commits and distinct authors in the window |330| `INSERTIONS` / `DELETIONS` / `NET_LOC` | Raw LOC, generated output (`build/`, `dist/`, `node_modules/`, ...) excluded |331| `TEST_INSERTIONS` / `TEST_RATIO` | Lines added in test files (test dirs, `.test.` / `_spec.` suffixes, `test_*.py`, `.bats`; prose never counts) |332| `WEIGHTED_COMMITS` | Commits x files touched, capped at 20 per commit |333| `ACTIVE_DAYS` | Distinct local dates with commits |334| `SESSIONS` | 45-minute-gap sessions: deep 50+ min, medium 20-50, micro under 20 (usually single-commit) |335| `TOTAL_ACTIVE_MINUTES` / `AVG_SESSION_MINUTES` / `LOC_PER_SESSION_HOUR` | Session time (LOC/hour rounded to the nearest 50) |336| `COMMIT_TYPES` / `FIX_RATIO` | Conventional-commit prefixes; ytstack task commits (`M###-S##-T##:`) count as `task` |337| `COMMIT_SIZE_BUCKETS` | small under 100 / medium 100-500 / large 500-1500 / xl 1500+ LOC per commit |338| `HOURS` / `PEAK_HOUR` | Hourly commit histogram, local time, nonzero hours only |339| `FOCUS_SCORE` | Share of file changes in the busiest top-level directory |340| `BIGGEST_COMMIT` | Highest-LOC commit (ship-of-the-milestone candidate) |341| `HOTSPOT: count file` | Ten most-changed files |342| `AUTHOR: name\|commits\|+ins/-del\|tests N%\|biggest ...` | Per-contributor rollup with their biggest commit |343| `COAUTHOR` / `AI_ASSISTED_COMMITS` | Human co-author credit; commits with an AI co-author trailer |344| `PR_REFS` | `#NNN` references in subjects (not verified merges) |345| `TEAM_STREAK` / `USER_STREAK` | Consecutive commit days, anchored at the newest commit date |346347**Identity:** `USER_NAME` is "you", the person reading the retro. Every other author is a teammate.348349**Freshness guard.** Evaluate in order:3503511. If `GUARD_REMOTE: none` or `RETRO_FETCH` failed: proceed, and carry "offline run, window not freshness-verified" into the report.3522. If the fetch succeeded and `COMMITS: 0` and `GUARD_LATEST_COMMIT` is older than the window start: stop with "Retro window is stale. Latest commit on `<RETRO_REF>` is `<date>`, but the window covers `<since>` to today. Either today's date is wrong in this session or the base branch is behind. Check the date, run `git fetch origin <base>`, then run `ytstack:retro` again."3533. If `COMMITS: 0` otherwise: say so, suggest a wider window (`ytstack:retro 30d`), and continue with summaries only; every git-derived section then reads `no commits in window`.3544. If `BASE_COMMITS_NOT_IN_HEAD` is above 0, say once in the report that the branch has not merged the latest base (that many base commits are not counted); the metrics still describe `HEAD`, which carries the milestone's work.355356### 6. Shipping outcomes357358- **Merged PRs** (only if `HAS_GH=yes`): `gh pr list --state merged --base "<base>" --search "merged:>=<start-date>" --limit 1000 --json number,title,mergedAt`. Filter `mergedAt` to the exact window, upper bound included in `compare` mode. At the limit, label the count partial. Without `gh`, show **PRs referenced** from `PR_REFS` and say they are not verified merges.359- **Features shipped** (only if `CHANGELOG=yes`): `git log <RETRO_REF> --since "<since>" -p -- CHANGELOG.md` (add `--until` for the prior window). Combine new user-visible capabilities with verified merged PR titles; dedupe entries for the same capability; exclude fixes, chores and reverted work. Keep a short list with the source commit or PR beside each. With neither source: `unavailable`, not 0.360- **Backlog** (only if `TODOS=yes`): read `TODOS.md`; count open items (outside a `## Completed` section), P0/P1, P2, items completed in the window (dated Completed entries), items added in the window (`COMMIT:` lines that touched `TODOS.md`).361362### 7. Analyze363364Build each block from the metric lines; anchor every claim in `COMMIT:` lines or summaries.365366- **Summary table.** Lead with what shipped, then volume. Raw LOC is context, not impact.367368 | Metric | Value |369 | --- | --- |370 | Tasks closed (summaries) | N of PLAN_TASKS total |371 | Features shipped (CHANGELOG + merged PRs) | N |372 | Commits to `<RETRO_REF>` | N |373 | Weighted commits | N |374 | Contributors | N |375 | PRs merged (or referenced) | N |376 | Raw LOC: +ins / -del / net | N / N / N |377 | Test LOC ratio | N% |378 | Active days | N |379 | Sessions (deep / medium / micro) | N (a / b / c) |380 | LOC per session-hour | N |381 | AI-assisted commits | N of M |382 | Backlog (only if TODOS) | N open (X P0/P1, Y P2), Z completed |383384 Below it, a per-author leaderboard from `AUTHOR:` lines, sorted by commits, with the current user first as "You (name)". Solo repo: one line, no team framing.385- **Time distribution.** Render `HOURS` as a histogram (`14: 50 ██████████`). Call out peak hours, dead zones, bimodal vs continuous, and late-night clusters (after 22:00).386- **Sessions.** Count and the deep / medium / micro split, total active time, average length, LOC per hour.387- **Commit types.** Render `COMMIT_TYPES` as a percentage bar. Flag `FIX_RATIO` above 50%: "ship fast, fix fast" often means review gaps. Look for fix chains (several fixes on the same subsystem in a row).388- **Hotspots.** Files changed 5+ times are churn; tests vs production files in the list; how often VERSION / CHANGELOG appear (release discipline). Cross-check: a churning file that no summary mentions under Deviations is a finding.389- **Commit sizes.** The four buckets and what they say about reviewability.390- **Focus + ship of the milestone.** `FOCUS_SCORE` with the directory ("Focus: 62% in `app/services/`"). `BIGGEST_COMMIT`: PR number if the subject carries one, LOC, and why it matters (from the subject, the files, and the summary that owns it). A vendored-import or generated commit is not a ship; pick the biggest authored one and say why.391- **People** (skip for a solo repo; the retro is personal then). For the current user: sessions, peak hours, focus, biggest ship. For each teammate: 2-3 sentences on what they worked on, 1-2 specific praise points anchored in commits, 1 growth suggestion tied to data. Credit `COAUTHOR:` humans next to the primary author. AI co-authors are the `AI_ASSISTED_COMMITS` metric, never a team member; state the share neutrally.392- **Week-over-week** (only if the window is 14 days or longer). Group `COMMIT:` lines by week (newest week first): commits per week, per author, and fix ratio per week. For LOC and test ratio per week, re-run the step 5 command with one `<since>` / `<until>` pair per week.393- **Streaks.** Interpret `TEAM_STREAK` / `USER_STREAK` against today: anchor today or yesterday = live streak; older = broken, report 0 days and the last commit day.394395### 8. Milestone outcomes396397This is the part a calendar retro cannot give. From the material read in step 3:398399- **Exit criteria.** One line per criterion in `M###-CONTEXT.md`: `met` / `partly` / `not met`, each with the summary or commit that proves it.400- **Plan completion.** `PLAN_TASKS` done vs total, per slice; name any open task.401- **Verification.** Count summaries by `verification:` value (`passed`, `passed_with_caveats`, `failed`); list each caveat in one line.402- **Deviations.** Every non-empty Deviations section, grouped by cause (plan was wrong, scope grew, tool or environment surprise, upstream change). Repeated causes are the strongest lesson candidates.403- **Follow-ups.** Every follow-up from the summaries, marked `done` (a later commit or summary resolves it) or `open`. Open follow-ups are candidates for the next milestone, not for silent dropping.404- **Summaries vs git.** Where the two witnesses disagree (a "clean" task next to a fix chain, a task with no commits in the window, commits with no task), say so plainly.405- **Own reviewers vs bots** (only if `OWN_REVIEWERS` is not `none`). Read from the signals ledger, never from the host. The counts come from `.ytstack/signals/review-checks` (format: `docs/ux/signal-format.md`, "Review escapes"): one line per checked merged pull request, `<owner/name>#<n> <merge sha> <check time> [<tally>]`, the tally `<role>=<caught>/<escaped>` comma separated, or `none`. Take the lines whose check time lies in the window and sum caught and escaped per role; the escape rate of a role is escaped / (caught + escaped), `n/a` at 0. `-` collects escapes no role owns: show it as its own row, it is a gap in the roles. A line without a tally was written before tallies existed: list those pull requests as "not recorded" and leave them out of the sums, never count them as 0. The classes come from the findings between `REVIEW_FINDINGS_BEGIN` and `REVIEW_FINDINGS_END`: per role the keys and their state. One row per role of `OWN_REVIEWERS`, a role without findings included:406407 | Role | Caught | Escaped | Escape rate | Classes (open / planned / fixed / dismissed) | Proposed (`ref` a question) |408 | --- | --- | --- | --- | --- | --- |409410 Above the table: how many checked pull requests the window has, how many of them without a tally, and how many merged pull requests step 6 found, when it found any; a gap means pull requests had no escape check. A class whose count is 2 or more and that is still `open` without a question is a candidate for "3 Things to Improve". Put the table under `## Milestone Outcomes` and `"review_escapes": {"<role>": {"caught": <n>, "escaped": <n>}, ...}` into the snapshot.411- **Incidents and lessons** (only if `LESSONS` is above 0). Read from the signals ledger (`docs/ux/signal-format.md`, "Lessons"): every incident of any class left a sighting on the lesson of its class. Run, with the window start of step 4 as a UTC time:412413 ```bash414 bash "<SIGNALS_TOOL>" lesson list --state all --since <since, e.g. 2026-11-01T00:00:00Z>415 ```416417 One line per lesson: id, state, area, class, count, sightings in the window, target, ref, reopens, title. Show the lessons with at least one sighting in the window, grouped by area, one row per class:418419 | Area | Class | Incidents in window | All time | Repeat | Where the lesson lives | State |420 | --- | --- | --- | --- | --- | --- | --- |421422 `Repeat` is `yes` when the class counts 2 or more, or when the lesson reopens an earlier one (`reopens` is not `none`: the lesson that was in place did not hold). Above the table: the incidents in the window per area, and how many classes repeated. Only the newest five sightings of a class stay in its file, so a class with more in the window says "at least 5". A repeated class whose lesson is still a proposal or only a knowledge entry is a candidate for "3 Things to Improve" (name its id), and a reopened one is always one. Put `"lessons": {"incidents": <n>, "classes": <n>, "repeats": <n>, "open": <n>}` into the snapshot.423424### 9. Compare with the prior retro425426Only if `PRIOR_RETRO` is not `none`, or in `compare` mode.427428- **Trends.** From the prior retro's `## Snapshot` JSON (or, in `compare` mode, the prior-window metrics), show a **Trends** table: test ratio, sessions, deep sessions, LOC per hour, fix ratio, commits, tasks per active day. Ratio changes in percentage points; a zero prior value gives `n/a` for the percentage. Prior milestones differ in length, so say so when the windows differ by more than 2x and prefer per-day rates.429- **Recommendation follow-through.** Score each prior `recommendations` item as `addressed`, `partial` or `open` against this window's commits, changed files and summaries, citing the evidence. One headline ("2 of 3 prior recommendations addressed"), then one line per item. Skip silently when the snapshot has no `recommendations` key.430- No prior retro and no `compare`: append "First retro recorded; the next milestone's retro will show trends."431432### 10. Ask before replacing433434Only if `RETRO_EXISTS=yes`. Check `git status --short -- <RETRO_FILE>` first; an uncommitted file would be lost on replace, so say so in the question.435436In `YTSTACK_NON_INTERACTIVE: true` mode, auto-pick A and log: "[ytstack:retro] auto-picked A (replace) because YTSTACK_NON_INTERACTIVE=true".437438Otherwise use AskUserQuestion:439440> I'm writing the retro for `<MILESTONE>` of `<PROJECT_SLUG>` on branch `<BRANCH>`, and `<RETRO_FILE>` already exists (<committed / has uncommitted changes>).441>442> A retro for this milestone was written before. Replacing it keeps the old version in git history if it was committed; if it has uncommitted edits, those are gone. Keeping it means this run ends without writing anything.443>444> RECOMMENDATION: Choose A because the new retro covers the milestone's final state and the old one stays recoverable in git.445>446> A) Replace the file with the new retro447> Completeness: 10/10, effort: human: 0 / CC: ~1 min, tier: task448>449> B) Keep the existing file and stop450> Completeness: 3/10, effort: human: 0 / CC: 0, tier: task451452If B: show the report in the conversation only, skip steps 11 and 12, and report "kept existing `<RETRO_FILE>`".453454### 11. Write `M###-RETRO.md`455456Draft the one-line summary and the "3 Things to Improve" first; the snapshot reuses them verbatim. Write `RETRO_FILE` with the Write tool:457458````markdown459---460milestone: <MILESTONE>461project: <PROJECT_SLUG>462created: <ISO-8601 UTC timestamp>463---464465# <MILESTONE> -- Retro466467<one-line summary: "M016 (Nov 1-7): 14 tasks, 132 commits, 26% tests, 3 PRs, peak 14:00, 1 deviation pattern">468469## Summary470<summary table + leaderboard from step 7>471472## Milestone Outcomes473<exit criteria, plan completion, verification, deviations, follow-ups, summaries vs git from step 8>474475## Trends vs Last Retro476<step 9 table + recommendation follow-through; or the first-retro line; in compare mode "Current vs Prior Window">477478## Time & Session Patterns479<histogram + narrative: when the productive hours are, session length, estimated active hours per day, whether people work in parallel or in shifts>480481## Shipping Velocity482<commit types, size buckets, fix chains, release discipline>483484## Code Quality Signals485<test ratio and trend, hotspots, churn without a matching deviation>486487## Focus & Highlights488<focus score, ship of the milestone>489490## Streaks491<team + personal, broken-streak disclosure>492493## Your Milestone494<personal deep-dive for USER_NAME: commits, LOC, test ratio, sessions, peak hours, focus, biggest ship; **What you did well** (2-3, anchored in commits); **Where to level up** (1-2, actionable)>495496## Team Breakdown497<per teammate, sorted by commits: what they shipped, praise, one growth opportunity; omit the section for a solo repo>498499## Top 3 Wins500<what, who, why it matters for the product or architecture>501502## 3 Things to Improve503<specific, actionable, each naming a concrete file, script or check, so the next retro can score it>504505## 3 Habits for the Next Milestone506<each adoptable in under 5 minutes; at least one team-oriented when there is a team>507508## Upstream509<filled in step 13: what of this milestone concerns ytstack itself, and what happened to it>510511## Snapshot512513```json514{ "milestone": "M016", "window": "2026-11-01..2026-11-07", "metrics": { "commits": 132, "contributors": 1, "prs_merged": null, "insertions": 33620, "deletions": 8431, "test_ratio": 0.26, "active_days": 1, "sessions": 1, "deep_sessions": 1, "loc_per_session_hour": 7400, "fix_pct": 0.01, "peak_hour": 14, "ai_assisted_commits": 7, "tasks_done": 14, "tasks_total": 14 }, "streak_days": 1, "summary": "<the one-line summary>", "recommendations": [ { "category": "testing", "text": "<item 1 verbatim>" } ] }515```516````517518Rules for the file:519520- Size every section to its evidence. A section with nothing to say is cut, not padded. Keep `## Summary`, `## Milestone Outcomes`, `## 3 Things to Improve`, `## Upstream` and `## Snapshot` always.521- `prs_merged` is `null` when hosting data was unavailable. `recommendations` is always present: one object per "3 Things to Improve" item with a one-word lowercase category and the item text verbatim; `[]` when there are none, never padded.522- Add `"backlog": {...}` only when `TODOS=yes`, `"review_escapes": {...}` only when `OWN_REVIEWERS` is not `none`, and `"lessons": {...}` only when `LESSONS` is above 0.523- After writing, show the report (everything above `## Snapshot`) in the conversation.524525**Tone.** Encouraging but candid, no coddling. Specific and concrete, always anchored in commits or summaries. No generic praise ("great job"): say what was good and why. Praise sounds like something you would say in a 1:1. Growth suggestions sound like investment advice ("worth your time because..."), not "you failed at". Never compare teammates against each other negatively. Tables and code blocks for data, prose for narrative. If the test ratio is under 20%, flag it as a growth area.526527### 12. Propose lessons528529From the deviations, follow-ups, summaries-vs-git disagreements and the "3 Things to Improve", draft:530531- **KNOWLEDGE entries**: patterns, pitfalls, gotchas that would save a future session 5+ minutes. One bullet each, in the style of the existing `KNOWLEDGE.md` sections (bold lead, one or two sentences, a concrete file or command).532- **DECISIONS entries**: only choices made during the milestone that outlive it and are not yet in `DECISIONS.md`. Use the file's own entry format (`## YYYY-MM-DD: <title>` with Context / Options considered / Chose / Reason).533534Skip anything obvious, anything already in either file (grep first), and one-off transient errors. If nothing qualifies, say "No durable lessons this milestone" and skip the question.535536Show the drafted entries as a numbered list. In `YTSTACK_NON_INTERACTIVE: true` mode, auto-pick A and log: "[ytstack:retro] auto-picked A (write all) because YTSTACK_NON_INTERACTIVE=true". Otherwise use AskUserQuestion:537538> The `<MILESTONE>` retro for `<PROJECT_SLUG>` on branch `<BRANCH>` is written to `<RETRO_FILE>`. I drafted <K> KNOWLEDGE and <D> DECISIONS entries (listed above).539>540> These files are the project's long-term memory: every future session reads them, so a lesson written there stops the same mistake from happening twice. A lesson that stays only in the retro is read once and forgotten.541>542> RECOMMENDATION: Choose A because every entry is drafted from evidence in this milestone and none duplicates an existing one.543>544> A) Write all drafted entries545> Completeness: 10/10, effort: human: 0 / CC: ~1 min, tier: task546>547> B) Let me pick entry by entry548> Completeness: 8/10, effort: human: ~2 min / CC: ~1 min, tier: task549>550> C) Write none, keep the lessons in the retro only551> Completeness: 4/10, effort: human: 0 / CC: 0, tier: task552553- A: append every entry (KNOWLEDGE under the fitting section, DECISIONS at the end, never rewriting past entries).554- B: ask one yes/no question per entry, in order, each re-grounded with the entry text; write the yes entries.555- C: write nothing.556557Then add a `## Lessons recorded` line to `RETRO_FILE` (before `## Upstream`) naming what went where.558559### 13. Upstream560561The project's lessons went into its own files in step 12. This step is about ytstack itself: a skill, hook or script of the plugin that misled, failed or was missing, a workaround built around one, a ytstack tool that ran against a real host for the first time. The channel and its rules: `${CLAUDE_SKILL_DIR}/../../docs/ux/upstream-feedback.md`; read its "The steps" and "The rules" before acting.562563From the material of steps 3 to 8 (deviations caused by a tool surprise, workarounds in summaries, follow-ups and "3 Things to Improve" that name a ytstack skill or script), list the observations that concern ytstack, one per line with its kind (`bug`, `gap`, `proposal`, `evidence`) and the evidence (summary, commit, count). Nothing qualifies, or the project is ytstack itself (its own artifacts are the place): write "Nothing this milestone concerns ytstack itself." under `## Upstream` and go on. Otherwise, by `UPSTREAM_FEEDBACK`:564565- `off`: write `upstream_feedback: off` and the list under `## Upstream`, send nothing, suggest nothing.566- `suggest` or `unavailable`: per observation, search, draft with `"<UPSTREAM_TOOL>" draft`, fill it, run `check` until `draft ok`. Send nothing. Each line under `## Upstream` ends with `suggested: <draft path>` (and `matches #<n>` when the search found the same behaviour).567- `file`: per observation, search, draft, fill, `check`, then `gh issue create` or, for a match, `gh issue comment`, as the document says. Each line ends with `filed #<n>` or `commented #<n>`. A draft that does not pass `check` is not sent: the line ends with `not sent: <the check's line>`.568569In `YTSTACK_NON_INTERACTIVE: true` mode nothing is sent under any setting: the lines end with `suggested: <draft path>` and the report lists them under "Waiting on a person".570571### 14. Re572573…(truncated)