项目小结（Project Retro Summary）
把「散落在几十份报告里的项目历史」压缩成一份能被信任的现状快照。
触发场景
- 「做项目小结」「整理归类项目文档」「分析梳理项目结构」「总结阶段功能实现的路径」「给出最新评价和开发方案」
- 接手一个别人迭代了很久的项目，需要快速建立全局认知
- 上线前/汇报前，需要一份有据可查的现状说明
核心原则（先说反直觉的三条）
-
不读全部文档，但必须读全部文档的"索引层"。
74 份交付报告逐份读会耗尽上下文且收益递减。正确做法：读索引/状态册/最新总览（它们本身就是为这个目的写的），再用grep '^## '批量提取所有日报的标题 —— 标题就是时间轴。 -
结构必须实测，不能照抄文档。
文档里写的「架构」往往是设计意图，不是现状。必须去真实环境测量：文件行数、目录树、版本号、git log。文档说 7 步工作流，代码里可能是 5 个巨型文件。 -
「已证伪的伪问题」比「待办」更值钱。
长期项目的待办列表里混着伪问题（照做会造成损失）。小结必须单列一节，否则下一个人会重新踩。
五阶段流程
Phase 1 · 盘点（Document Inventory）
# 1.1 文档总量与分布
ls -la *.md *.html | wc -l # 交付报告
ls -la .workbuddy/memory/ # 日报 + 记忆册
# 1.2 记忆册结构（通常有索引 + 子册）
head -30 .workbuddy/memory/MEMORY.md
# 1.3 ★ 关键技巧：批量提取所有日报的二级标题 = 免费时间轴
for f in .workbuddy/memory/20*.md; do
echo "##### $f"; grep -nE "^## " "$f" | head -40
done
产出：文档清单（数量 / 位置 / 性质）。
判据：能回答「哪几份是权威索引」「哪几份是过程记录」。
Phase 2 · 归类（Classification）
按主题簇归，不按时间归。典型簇：
| 簇 | 特征 |
|---|---|
| 主线功能迭代 | 同一模块的多轮演进报告 |
| 上游/外部依赖治理 | 限流、计费、第三方 API |
| 方案设计（文档 ≠ 实现） | ⚠️ 最容易过期的一簇 |
| 平台工程与外围 | CI/CD、MCP、skill 蒸馏 |
| 阶段总览 | overview / followups |
同时产出文档健康度问题表（必做）：
- 同题多版本 — 同一主题有 N 份设计文档，哪些已被实现文档覆盖
- 口径漂移 — 报告里的结论后来被推翻，文件里是否还留着旧结论
- 无索引 — 平铺的几十份报告缺一个目录
Phase 3 · 结构剖析（Structure Profiling）
必须在真实环境跑，不能照抄文档。
# 3.1 代码规模（行数比文件数有信息量）
wc -l $(git ls-files '*.js' | grep -v node_modules) | sort -rn | head -20
# 3.2 目录树（排除噪声目录）
find . -maxdepth 2 -type d -not -path "./node_modules*" -not -path "./.git*" | sort
# 3.3 版本与依赖
grep -E '"version"|"name"' package.json
# 3.4 git 历史（近期 commit 就是近期主线）
git log --oneline -15
# 3.5 测试资产清点（最容易被低估的资产）
ls scripts/test-*.js scripts/mutcheck-*.js 2>/dev/null
分层判定：对照入口（server.js）→ 编排 → 能力层的调用关系，标出结构性偏离（例如路由与 UI 全塞在单文件里）。
Phase 4 · 阶段路径（Path Reconstruction）
从日报标题 + 版本 CHANGELOG 双向拼时间轴。
版本轴：CHANGELOG.md（或 git tag）→ 宏观里程碑
日期轴：日报 `^## ` 标题 → 每个迭代轮次
关键要求：每个阶段要写「证伪点」。
一条主线之所以走了 6 个迭代，通常不是"功能越来越多"，而是每个迭代推翻上一个结论。把推翻链条写出来，才是真路径：
① 方案 X（阈值 A）
└ 证伪点：<哪条数据推翻了它>
② 方案 Y（阈值 B）
└ 证伪点：<踩了什么坑>
③ ...
同时输出「方法论演进路径」 —— 项目真正值钱的沉淀往往不是功能，而是验证方法的升级（例：验证金字塔从 4 层扩到 6 层、积累了 35 条铁律）。
Phase 5 · 评价 + 方案（Assessment & Roadmap）
评价必须带证据，三节固定结构：
| 节 | 内容 | 要求 |
|---|---|---|
| 做得好的 | 3~7 项 | 每项附具体数字（变异体数 / 阈值依据 / 回滚点） |
| 真正的风险 | 按严重度排序 | 每行必须有 证据列（md5 / 实测百分比 / 文件行数） |
| 已证伪的伪问题 | 列出"别再动手"的清单 | 每项附证伪依据（官方源码 / A/B 数据） |
方案按时间分层，且决策项与执行项分开：
立即（P0，阻塞解除） → 明确标注「需你拍板」的决策项，给 2~3 个带取舍的选项
短期（P1，1~2 轮）
中期（P2，架构级）
明确不建议做 ← 与"已证伪"呼应，防止下一个人重新踩
输出模板
# <项目名> · 项目小结
> 小结日期 · 版本 · 快照口径（实测环境 + 文档数量）
> **一句话**：<主体状态> + <近期投入在哪> + <当前唯一实质阻塞是什么>
## 一、文档资产盘点与归类
1.1 总量分布（表：类别/数量/位置/性质）
1.2 按主题归类（六大簇，带文件清单）
1.3 ⚠️ 文档健康度：三个需要治理的问题
## 二、项目结构剖析
2.1 系统全景（部署拓扑图）
2.2 代码结构（实机测量表：文件/行数/职责）
2.3 测试与验证资产
## 三、阶段功能实现路径
3.1 版本 / 阶段时间轴
3.2 主线实现路径（带证伪点的链条）
3.3 ★ 方法论演进路径
## 四、最新评价
4.1 做得好的
4.2 真正的风险（按严重度 + 证据列）
4.3 🔴 已证伪的伪问题（别再动手）
## 五、开发方案
5.1 立即（含需拍板的决策项）
5.2 短期
5.3 中期
5.4 明确不建议做
## 六、未闭环清单
附 · 关键文件哈希速查
陷阱清单（都真实踩过）
| # | 陷阱 | 规避 |
|---|---|---|
| 1 | 逐份读几十个报告 → 上下文爆炸且收益递减 | 先读索引层 + grep '^## ' 提标题 |
| 2 | 照抄文档里的架构描述 → 写的是设计意图不是现状 | 必须实测：wc -l / 目录树 / git log |
| 3 | 只看"未完成待办" → 把伪问题当任务派下去 | 单列「已证伪的伪问题」节 |
| 4 | 报告里的旧结论已撤回但文件没改 | 检索关键词（如 已撤回 / 更正 / 证伪）再引用 |
| 5 | 同题多版本设计文档冒充现状 | 用文件 mtime 排序，标注「设计期文档，实现以 X 为准」 |
| 6 | 拿 dev 环境当性能基线 | 先查 uptime / swap / 是否有干扰进程占资源 |
| 7 | 小结写完不留索引 | 把 §1.2 归类表直接当文档索引附录落盘 |
| 8 | 只写"做完了什么"，不写"推翻了什么" | 每个阶段强制填「证伪点」 |
交付物
项目小结-<项目名>-<日期>.md— 主交付（放工作区根目录）- skill 本体 — 本文件（可复用流程）
- 记忆落盘 — 把「当前阻塞」「状态速查」写进
.workbuddy/memory/MEMORY.md - present_files 展示 — 主文档 + 总览
自检清单
- [ ] 文档总数、日报数、记忆册数都报了实际数字
- [ ] 代码规模是实测的（行数 / 目录树 / 版本号）
- [ ] 时间轴覆盖到项目起点（版本轴或 CHANGELOG），不只是近几天
- [ ] 每条风险都有证据列（不能写"可能有问题"）
- [ ] 「已证伪的伪问题」节非空（长期项目必然有）
- [ ] 方案里的决策项与执行项分开，决策项给了带取舍的选项
- [ ] 未闭环清单与风险表不重复（前者是"没做完"，后者是"做得不对"）
