retro

运行时说明

• 工作流要求暂停并等待输入时，请直接询问用户。
• 将 AGENTS.md、TODO.md 和 TODOS.md 视为仓库本地说明的可能来源。
• 保持工作流意图不变，但将特定于环境的措辞调整为当前工具集。

/retro — 每周工程复盘

生成全面的工程复盘，分析提交历史、工作模式和代码质量指标。了解团队情况：识别运行命令的用户，然后分析每位贡献者，并针对个人给予肯定和指出成长机会。适用于将编码 Agent 作为效率倍增器的资深个人贡献者／CTO 级构建者。

用户可调用

当用户要求进行复盘或调用 retro 时，使用此技能。

参数

• retro — 默认：最近 7 天
• retro 24h — 最近 24 小时
• retro 14d — 最近 14 天
• retro 30d — 最近 30 天
• retro compare — 对比当前时间窗口与之前同等长度的时间窗口
• retro compare 14d — 与指定时间窗口进行对比

说明

解析参数以确定时间窗口。如果未提供参数，则默认为 7 天。执行 git log 查询时，使用 --since="N days ago"、--since="N hours ago" 或 --since="N weeks ago"（w 单位）。所有时间均应以太平洋时间报告（转换时间戳时使用 TZ=America/Los_Angeles）。

参数验证： 如果参数不符合数字后跟 d、h 或 w，单词 compare，或 compare 后跟数字和 d``h``w 的格式，请显示以下用法并停止：

Usage: /retro [window]
  /retro              — last 7 days (default)
  /retro 24h          — last 24 hours
  /retro 14d          — last 14 days
  /retro 30d          — last 30 days
  /retro compare      — compare this period vs prior period
  /retro compare 14d  — compare with explicit window

步骤 1：收集原始数据

首先，获取 origin 并识别当前用户：

git fetch origin main --quiet
# Identify who is running the retro
git config user.name
git config user.email

git config user.name 返回的名称就是**“你”**，也就是阅读此复盘的人。其他所有作者都是队友。叙述时据此区分“你的”提交和队友的贡献。

并行运行以下所有 git 命令（这些命令互不依赖）：

# 1. All commits in window with timestamps, subject, hash, AUTHOR, files changed, insertions, deletions
git log origin/main --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat

# 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/main --since="<window>" --format="COMMIT:%H|%aN" --numstat

# 3. Commit timestamps for session detection and hourly distribution (with author)
#    Use TZ=America/Los_Angeles for Pacific time conversion
TZ=America/Los_Angeles git log origin/main --since="<window>" --format="%at|%aN|%ai|%s" | sort -n

# 4. Files most frequently changed (hotspot analysis)
git log origin/main --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn

# 5. PR numbers from commit messages (extract #NNN patterns)
git log origin/main --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'

# 6. Per-author file hotspots (who touches what)
git log origin/main --since="<window>" --format="AUTHOR:%aN" --name-only

# 7. Per-author commit counts (quick summary)
git shortlog origin/main --since="<window>" -sn --no-merges

步骤 2：计算指标

计算并在摘要表中展示以下指标：

指标	值
提交到 main 的次数	N
贡献者	N
已合并的 PR	N
总新增行数	N
总删除行数	N
新增净 LOC	N
测试代码 LOC（新增）	N
测试代码 LOC 比例	N%
版本范围	vX.Y.Z.W → vX.Y.Z.W
活跃天数	N
检测到的会话数	N
每会话小时平均 LOC	N

然后在下方立即显示按作者排列的排行榜：

Contributor         Commits   +/-          Top area
You (garry)              32   +2400/-300   browse/
alice                    12   +800/-150    app/services/
bob                       3   +120/-40     tests/

按提交数降序排序。当前用户（来自 git config user.name）始终排在第一位，标记为“You (name)”。

步骤 3：提交时间分布

使用柱状图展示太平洋时间的每小时分布：

Hour  Commits  ████████████████
 00:    4      ████
 07:    5      █████
 ...

指出并说明：

• 高峰时段
• 空档时段
• 工作模式是双峰（上午／晚上）还是连续分布
• 深夜编码集中时段（晚上 10 点后）

步骤 4：工作会话检测

使用45 分钟的间隔阈值检测会话，即连续提交之间的间隔。报告每个会话的：

• 开始／结束时间（太平洋时间）
• 提交数
• 时长（分钟）

会话分类：

• 深度会话（50 分钟以上）
• 中等会话（20–50 分钟）
• 微型会话（少于 20 分钟，通常是单次提交后即告结束）

计算：

• 总活跃编码时间（会话时长总和）
• 平均会话时长
• 活跃时间内每小时 LOC

步骤 5：提交类型细分

按 Conventional Commits 前缀（feat/fix/refactor/test/chore/docs）分类。使用百分比条展示：

feat:     20  (40%)  ████████████████████
fix:      27  (54%)  ███████████████████████████
refactor:  2  ( 4%)  ██

如果 fix 占比超过 50%，则标记出来——这表明存在“快速发布、快速修复”的模式，可能意味着审查存在疏漏。

步骤 6：热点分析

显示变更最多的前 10 个文件。标记：

• 变更 5 次以上的文件（频繁变更热点）
• 热点列表中的测试文件与生产文件
• VERSION/CHANGELOG 变更频率（版本管理规范的指标）

步骤 7：PR 大小分布

根据提交差异估算 PR 大小，并按以下区间分类：

• 小型（少于 100 LOC）
• 中型（100–500 LOC）
• 大型（500–1500 LOC）
• 超大型（1500 以上 LOC）——标记这些 PR 涉及的文件数量

第 8 步：专注度评分 + 本周交付成果

专注度评分： 计算涉及改动最多的顶层目录（例如 app/services/、app/views/）的提交占比。评分越高 = 工作越专注深入。评分越低 = 上下文切换越频繁。报告格式：「专注度评分：62%（app/services/）」

本周交付成果： 自动找出此时间范围内代码行数（LOC）最多的单个 PR，并重点介绍：

• PR 编号和标题
• 变更的 LOC
• 重要性（根据提交信息和涉及的文件推断）

第 9 步：团队成员分析

对每位贡献者（包括当前用户）计算：

1. 提交和 LOC — 提交总数、新增行数、删除行数、LOC 净值
2. 专注领域 — 他们改动最多的目录/文件（前 3 名）
3. 提交类型构成 — 个人的 feat/fix/refactor/test 分类
4. 工作时段模式 — 他们的编码时间（高峰时段）、工作时段数
5. 测试规范性 — 个人测试 LOC 占比
6. 最大交付成果 — 此时间范围内影响最大的单个提交或 PR

对于当前用户（「你」）： 本节应进行最深入的分析。包含独立回顾中的全部细节——工作时段分析、时间模式、专注度评分。使用第一人称表述：「你的高峰时段……」「你最大的交付成果……」

对于每位队友： 用 2-3 句话概述他们的工作内容和模式。然后：

• 表扬（1-2 项具体内容）：以实际提交为依据。不要说「做得很棒」——要具体说明做得好的地方。示例：「在 3 个专注的工作时段内完成整个认证中间件重写，测试覆盖率达 45%」「每个 PR 都少于 200 LOC，拆分工作做得很有条理。」
• 成长机会（1 项具体内容）：将其表述为提升建议，而不是批评。以实际数据为依据。示例：「本周测试占比为 12%——在支付模块变得更复杂之前补充测试覆盖会很有帮助」「同一文件有 5 次修复提交，这表明最初的 PR 可能需要多一次审查。」

如果只有一位贡献者（个人仓库）： 跳过团队分析，按之前的方式继续——回顾只针对个人。

如果存在 Co-Authored-By 尾注： 解析提交信息中的 Co-Authored-By: 行。除主要作者外，也将这些作者列为该提交的贡献者。注明 AI 联合作者（例如 [email protected]），但不要将其列为团队成员——应将「AI 辅助提交」作为单独指标统计。

第 10 步：逐周趋势（如果时间范围 >= 14d）

如果时间范围为 14 天或更长，按周分组并展示趋势：

• 每周提交数（总计及按作者统计）
• 每周 LOC
• 每周测试占比
• 每周修复占比
• 每周工作时段数

第 11 步：连续提交追踪

从今天开始向前统计连续有至少 1 次提交到 origin/main 的天数。追踪团队连续天数和个人连续天数：

# Team streak: all unique commit dates (Pacific time) — no hard cutoff
TZ=America/Los_Angeles git log origin/main --format="%ad" --date=format:"%Y-%m-%d" | sort -u

# Personal streak: only the current user's commits
TZ=America/Los_Angeles git log origin/main --author="<user_name>" --format="%ad" --date=format:"%Y-%m-%d" | sort -u

从今天开始向前统计——连续多少天至少有一次提交？此查询会检查完整历史，因此能准确报告任意长度的连续天数。显示两项：

• 「团队连续交付：47 天」
• 「你的连续交付：32 天」

第 12 步：加载历史记录并进行比较

保存新的快照之前，先检查是否有之前的回顾记录：

ls -t .context/retros/*.json 2>/dev/null

如果存在之前的回顾： 使用 Read 工具加载最近的一份。计算关键指标的变化，并加入 与上次回顾相比的趋势 部分：

                    Last        Now         Delta
Test ratio:         22%    →    41%         ↑19pp
Sessions:           10     →    14          ↑4
LOC/hour:           200    →    350         ↑75%
Fix ratio:          54%    →    30%         ↓24pp (improving)
Commits:            32     →    47          ↑47%
Deep sessions:      3      →    5           ↑2

如果没有之前的回顾： 跳过比较部分，并附上：「已记录首次回顾——下周再次运行即可查看趋势。」

第 13 步：保存回顾历史

计算完所有指标（包括连续天数）并加载之前的历史记录用于比较后，保存 JSON 快照：

mkdir -p .context/retros

确定今天的下一个序号（将 $(date +%Y-%m-%d) 替换为实际日期）：

# Count existing retros for today to get next sequence number
today=$(TZ=America/Los_Angeles date +%Y-%m-%d)
existing=$(ls .context/retros/${today}-*.json 2>/dev/null | wc -l | tr -d ' ')
next=$((existing + 1))
# Save as .context/retros/${today}-${next}.json

使用 Write 工具按以下架构保存 JSON 文件：

{
  "date": "2026-03-08",
  "window": "7d",
  "metrics": {
    "commits": 47,
    "contributors": 3,
    "prs_merged": 12,
    "insertions": 3200,
    "deletions": 800,
    "net_loc": 2400,
    "test_loc": 1300,
    "test_ratio": 0.41,
    "active_days": 6,
    "sessions": 14,
    "deep_sessions": 5,
    "avg_session_minutes": 42,
    "loc_per_session_hour": 350,
    "feat_pct": 0.40,
    "fix_pct": 0.30,
    "peak_hour": 22,
    "ai_assisted_commits": 32
  },
  "authors": {
    "Garry Tan": { "commits": 32, "insertions": 2400, "deletions": 300, "test_ratio": 0.41, "top_area": "browse/" },
    "Alice": { "commits": 12, "insertions": 800, "deletions": 150, "test_ratio": 0.35, "top_area": "app/services/" }
  },
  "version_range": ["1.16.0.0", "1.16.1.0"],
  "streak_days": 47,
  "tweetable": "Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm"
}

第 14 步：撰写总结

按以下结构组织输出：

---

适合发推的摘要（第一行，置于其他内容之前）：

Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d

工程回顾：[日期范围]

汇总表

（来自步骤 2）

与上次回顾的趋势对比

（来自步骤 11，在保存前加载——如果是首次回顾则跳过）

时间与会话模式

（来自步骤 3-4）

解读团队整体模式及其意义：

• 效率最高的时段，以及促成高效的因素
• 随着时间推移，会话是在变长还是变短
• 每天的活跃编码时长估算（团队总计）
• 值得注意的模式：团队成员是在同一时间编码，还是轮班编码？

交付速度

（来自步骤 5-7）

解读以下内容：

• 提交类型分布及其反映的情况
• PR 大小管理（PR 是否保持小巧？）
• 修复链检测（同一子系统中连续出现的修复提交）
• 版本升级管理

代码质量信号

• 测试代码行数占比趋势
• 热点分析（是否总是同一批文件在频繁变更？）
• 是否有应该拆分的超大型 PR

专注度与亮点

（来自步骤 8）

• 专注度评分及解读
• 本周交付亮点

你的本周表现（个人深入分析）

（来自步骤 9，仅针对当前用户）

这是用户最关心的部分。请包含：

• 个人提交数、代码行数、测试占比
• 会话模式和高峰时段
• 专注领域
• 最大的交付成果
• 做得好的地方（2-3 项具体表现，以提交为依据）
• 提升空间（1-2 项具体且可执行的建议）

团队成员表现

（来自步骤 9，针对每位队友——如果仓库只有一人则跳过）

为每位队友（按提交数降序排列）撰写一个部分：

[姓名]

• 交付内容：用 2-3 句话介绍其贡献、专注领域和提交模式
• 值得表扬之处：具体指出 1-2 项做得好的地方，并以实际提交为依据。真诚表达——在一对一沟通中，你会如何评价？例如：
  • “用 3 个小型、易审查的 PR 清理了整个认证模块——拆分得恰到好处”
  • “为每个新端点添加了集成测试，而不只是覆盖正常情况”
  • “修复了导致仪表板加载耗时 2 秒的 N+1 查询”
• 成长机会：提出 1 项具体且有建设性的建议。将其表述为投入方向，而非批评。例如：
  • “支付模块的测试覆盖率只有 8%——在后续功能基于它构建前，值得投入精力提升覆盖率”
  • “5 个 PR 中有 3 个超过 800 行代码——将它们拆分开来有助于更早发现问题，也能让审查更轻松”
  • “所有提交都在凌晨 1-4 点完成——保持可持续的节奏，长期来看有助于代码质量”

**AI 协作说明：**如果许多提交带有 Co-Authored-By AI 尾注（例如 Codex、Copilot），请将 AI 辅助提交的百分比作为团队指标记录下来。保持中性表述，例如“有 N% 的提交使用了 AI 辅助”，不作评价。

团队 3 项最佳成果

找出整个团队在此时间范围内交付的影响力最大的 3 项成果。每项说明：

• 成果内容
• 交付者
• 重要性（对产品或架构的影响）

3 项改进建议

提出具体、可执行且以实际提交为依据的建议。结合个人和团队层面的建议。表述为“为了更进一步，团队可以……”。

下周的 3 个习惯

小巧、实用、可行。每项都必须能在 <5 分钟内养成。至少有一项应面向团队（例如，“当天审查彼此的 PR”）。

每周趋势

（如适用，来自步骤 10）

---

对比模式

当用户运行 retro compare（或 retro compare 14d）时：

1. 使用 --since="7 days ago" 计算当前时间范围的指标（默认为 7d）
2. 使用 --since 和 --until 计算紧邻当前时间范围之前、时长相同的时间范围，以避免重叠（例如，对于 7d 时间范围，使用 --since="14 days ago" --until="7 days ago"）
3. 显示带有变化量和箭头的并排对比表
4. 撰写简短说明，重点介绍最大的进步和退步
5. 仅将当前时间范围的快照保存到 .context/retros/（与普通回顾运行相同）；不要保存此前时间范围的指标。

语气

• 鼓励他人，但直言不讳，不要过度呵护
• 具体明确——始终以实际提交或代码为依据
• 跳过泛泛的赞美（例如“做得好！”），具体说明哪些方面做得好、为什么
• 将改进建议定位为提升水平的机会，而非批评
• 赞美应像是在一对一交流中真诚说出的话——具体、有依据、发自内心
• 成长建议应像投资建议——“这值得你投入时间，因为……”，而不是“你没能……”
• 绝不以贬低的方式拿团队成员互相比较。每个人的部分都应独立成立。
• 总输出约 3000–4500 个单词（团队成员部分可适当加长）
• 数据使用 Markdown 表格和代码块，叙述内容使用段落
• 直接在对话中输出——不要写入文件系统（.context/retros/ JSON 快照除外）

重要规则

• 所有叙述内容都直接在对话中发给用户。唯一可以写入的文件是 .context/retros/ JSON 快照。
• 所有 Git 查询都使用 origin/main（不要使用可能已过时的本地 main）
• 显示时间戳时，全部转换为太平洋时间（使用 TZ=America/Los_Angeles）
• 如果所选时间窗口内没有提交，请如实说明，并建议选择其他时间窗口
• 每小时代码行数（LOC）按最接近的 50 取整
• 将合并提交视为 PR 边界
• 不要阅读仓库文档或其他文档——此技能自成一体
• 首次运行时（没有之前的回顾），应妥善跳过比较部分