---
name: retro
description: >
  当用户要求工程复盘、查看开发节奏、分析提交历史或回顾近期工作时使用。
  基于 git 历史生成结构化的工程复盘报告，含提交分布、session 分析、
  测试覆盖趋势、热点文件和改进建议。
  触发短语：工程复盘、retro、回顾、开发节奏、最近干了什么、
  代码质量趋势、shipping velocity。
---

# 工程复盘技能

## 项目概览入口
- 项目定位、技术栈与目录入口请阅读：`../references/project-overview.md`

## 目的与触发
- 目的：从 git 历史中自动生成结构化的工程复盘报告，帮助团队了解开发节奏、代码质量趋势和改进方向。
- 触发：用户要求工程复盘、查看近期开发情况、分析提交历史。

## 参数

| 参数 | 默认值 | 示例 |
|------|--------|------|
| 时间窗口 | 7 天 | `retro 24h`、`retro 14d`、`retro 30d` |
| 对比模式 | 关闭 | `retro compare`、`retro compare 14d` |

## 工作流

### Step 1: 收集原始数据

先确定默认分支和当前用户：

```bash
DEFAULT_BRANCH=$(git remote show origin 2>/dev/null | grep 'HEAD branch' | awk '{print $NF}')
[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH="main"
git fetch origin "$DEFAULT_BRANCH" --quiet
git config user.name
```

`git config user.name` 返回的是"你"——正在看这份报告的人。所有其他作者是队友。

并行运行以下 git 命令（它们相互独立）：

```bash
# 1. 窗口内所有提交（含时间戳、作者、主题、文件统计）
git log "origin/$DEFAULT_BRANCH" --since="<window>" --format="%H|%aN|%ae|%ai|%s" --shortstat

# 2. 每次提交的文件级增删（区分测试文件与生产文件）
#    测试文件匹配: test/|spec/|__tests__|*.spec.*|*.test.*|testing/
git log "origin/$DEFAULT_BRANCH" --since="<window>" --format="COMMIT:%H|%aN" --numstat

# 3. 提交时间戳（用于 session 检测和小时分布）
git log "origin/$DEFAULT_BRANCH" --since="<window>" --format="%at|%aN|%ai|%s" | sort -n

# 4. 热点文件（按变更频率排序）
git log "origin/$DEFAULT_BRANCH" --since="<window>" --format="" --name-only | grep -v '^$' | sort | uniq -c | sort -rn

# 5. PR 编号（从提交信息中提取 #NNN）
git log "origin/$DEFAULT_BRANCH" --since="<window>" --format="%s" | grep -oE '#[0-9]+' | sed 's/^#//' | sort -n | uniq | sed 's/^/#/'

# 6. 每个作者的文件热点
git log "origin/$DEFAULT_BRANCH" --since="<window>" --format="AUTHOR:%aN" --name-only

# 7. 每个作者的提交计数
git shortlog "origin/$DEFAULT_BRANCH" --since="<window>" -sn --no-merges
```

### Step 2: 计算指标

计算并用表格展示：

| 指标 | 值 |
|------|-----|
| 提交到主分支 | N |
| 贡献者 | N |
| 合并 PR 数 | N |
| 总新增行 | N |
| 总删除行 | N |
| 净新增 LOC | N |
| 测试代码行（新增） | N |
| 测试代码比例 | N% |
| 活跃天数 | N |
| 检测到的 Session 数 | N |
| 每 Session 小时产出 LOC | N |

然后展示**按作者排行**：

```
贡献者            提交数    +/-          主要领域
你 (name)              32   +2400/-300   backend/src/modules/performance/
alice                  12   +800/-150    frontend/src/app/
```

当前用户始终排第一，标记为"你 (name)"。

### Step 3: 提交时间分布

用柱状图展示 24 小时分布：

```
时段  提交数  ████████████████
 09:    5      █████
 10:    8      ████████
 ...
```

标注：
- 高峰时段
- 静默时段
- 是否存在双峰模式（上午/晚间）
- 深夜编码集中（22 点以后）

### Step 4: 工作 Session 检测

使用 **45 分钟间隔**阈值检测 session。每个 session 报告：
- 开始/结束时间
- 提交数
- 持续时长（分钟）

分类：
- **深度 Session**（50+ 分钟）
- **中等 Session**（20-50 分钟）
- **微 Session**（<20 分钟，通常是单次提交）

计算：
- 总活跃编码时间
- 平均 session 时长
- 每小时活跃时间的 LOC 产出

### Step 5: 提交类型分析

按约定式提交前缀分类（feat/fix/refactor/test/chore/docs/style/perf）：

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

**如果 fix 比例超过 50%**，标记为"快速交付+快速修复"模式，可能意味着 review 环节需要加强。

### Step 6: 热点分析

展示变更频率最高的 10 个文件。标注：
- 变更 5+ 次的文件（高频热点）
- 测试文件 vs 生产文件在热点中的占比
- schema/migration 文件频率（数据库变更频率指标）

### Step 7: PR 规模分布

从提交差异估算 PR 规模并分桶：
- **Small** (<100 LOC)
- **Medium** (100-500 LOC)
- **Large** (500-1500 LOC)
- **XL** (1500+ LOC) — 标记并列出文件数

### Step 8: 聚焦度评分 + 本周之星

**聚焦度评分：** 计算提交中最集中的顶层目录占比。高分 = 深度聚焦，低分 = 上下文频繁切换。

**本周之星：** 自动识别窗口内变更行数最大的 PR，简要说明其影响。

### Step 9: 团队成员分析

对每个贡献者（包括当前用户）分析：
1. **提交与 LOC** — 总提交数、增删行、净 LOC
2. **聚焦领域** — 主要修改的目录/文件（Top 3）
3. **提交类型分布** — 个人的 feat/fix/refactor/test 比例
4. **Session 模式** — 编码高峰时段、session 数
5. **测试纪律** — 个人测试代码比例
6. **最大交付** — 窗口内个人最大影响力的提交或 PR

**对当前用户（"你"）**：最详细的深度分析，包含 session 分析、时间模式、聚焦度。

**对每个队友**：2-3 句话覆盖工作内容和模式，然后：
- **亮点**（1-2 个具体的好表现，锚定到实际提交）
- **成长建议**（1 个具体、建设性的建议，锚定到实际数据）

**如果只有一个贡献者**：跳过团队分析，报告围绕个人展开。

**AI 协作提示：** 如果提交中有 `Co-Authored-By` trailer 含 AI 相关邮箱（如 `noreply@anthropic.com`），统计"AI 辅助提交"比例作为独立指标。

### Step 10: 周对比趋势（窗口 >= 14 天时）

如果时间窗口 >= 14 天，按周拆分展示趋势：
- 每周提交数（总计和按人）
- 每周 LOC
- 每周测试比例
- 每周 fix 比例

### Step 11: Shipping Streak

统计到今天为止连续有提交到默认分支的天数：

```bash
git log "origin/$DEFAULT_BRANCH" --format="%ad" --date=format:"%Y-%m-%d" | sort -u
```

从今天往回数——连续多少天至少有一次提交？

### Step 12: 历史对比

检查是否有之前的复盘记录：

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

如果有前次记录：读取最新一份，计算关键指标的变化并展示趋势对比表：

```
                    上次        本次        变化
测试比例:         22%    →    41%         ↑19pp
Session 数:       10     →    14          ↑4
每小时 LOC:       200    →    350         ↑75%
Fix 比例:         54%    →    30%         ↓24pp (改善)
```

如果没有前次记录：跳过对比，附注"首次复盘记录——下周再跑一次即可看到趋势。"

### Step 13: 保存复盘快照

计算完所有指标后，保存 JSON 快照：

```bash
mkdir -p .context/retros
```

保存为 `.context/retros/{YYYY-MM-DD}-{N}.json`，schema：

```json
{
  "date": "2026-03-17",
  "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,
    "ai_assisted_commits": 32
  },
  "authors": {
    "Author Name": {
      "commits": 32,
      "insertions": 2400,
      "deletions": 300,
      "test_ratio": 0.41,
      "top_area": "backend/src/modules/performance/"
    }
  },
  "streak_days": 47
}
```

### Step 14: 输出报告

结构化输出：

---

**一句话摘要**（首行）：
```
本周回顾 Mar 10-17: 47 提交 (3 人), 3.2k LOC, 38% 测试, 12 PR, 高峰: 22 点 | Streak: 47 天
```

## 工程复盘: [日期范围]

### 指标总览
（来自 Step 2）

### 趋势对比
（来自 Step 12，首次跳过）

### 时间与 Session 模式
（来自 Step 3-4，含叙述解读）

### 交付速度
（来自 Step 5-7，含叙述）

### 代码质量信号
- 测试代码比例趋势
- 热点分析（同一文件是否频繁变更？）
- 超大 PR 是否应该拆分

### 聚焦度与亮点
（来自 Step 8）

### 你的本周
（来自 Step 9，当前用户个人深度分析）

### 团队成员
（来自 Step 9，每个队友的分析）

### 团队 Top 3 成果

### 3 个改进方向
具体、可行、锚定到实际提交。

### 下周 3 个习惯
小的、实际的、现实的。每个不超过 5 分钟即可开始执行。

---

## 对比模式

当用户运行 `retro compare` 时：
1. 计算当前窗口指标
2. 计算前一个同长窗口指标（用 `--since` 和 `--until` 避免重叠）
3. 并排对比表，含变化箭头
4. 简要叙述最大改善和退步
5. 仅保存当前窗口快照

## 语气

- 鼓励但坦诚，不拍马屁
- 具体、锚定到实际提交——不说"做得好"，说具体做了什么好
- 改进建议框架为"投资"而非"批评"
- 不在队友之间做负面对比
- 总输出 2000-4000 字
- 数据用表格和代码块，叙述用散文
- 输出直接到对话——**唯一写入文件的是** `.context/retros/` 的 JSON 快照

## 禁止事项

- 不读 CLAUDE.md 或其他文档——本 skill 自包含
- 所有 git 查询用 `origin/<default>`（不用本地 main，可能过时）
- 零提交时提示并建议换个时间窗口
- LOC/小时四舍五入到最近 50
- 合并提交视为 PR 边界