# TVU 消费产品 · AI 协作复盘格式 spec

> **真源**：`tvu-design-system/templates/consumer-product/docs/retrospects/RETROSPECT_FORMAT.md`
> **适用**：所有 TVU 消费产品 session 收尾时写的 AI-用户协作复盘
> **配套规则**：`consumer-product-conventions` skill Rule 1（wrap-up → 写复盘 + commit + push）
> **标杆参考**：`MicroApps/docs/retrospects/2026-05-20-video-sync-mockup-retrospect-internal-share.md`（首版示范）

---

## 何时写复盘

**触发关键词**（用户在 consumer cwd 中说）：
- 收尾 / wrap up
- 复盘 / retrospect

AI 看到关键词后**强制执行**：
1. 按本格式写 `.md` 长读版（项目级 `docs/retrospects/` 目录）
2. 写配套 `.slides.md` Marp 源（用 `_template.slides.md` 骨架）
3. **不自动跑 marp 导出**（按 [[consumer-product-conventions]] Rule 4，按需触发）
4. `git add` + commit + push gitea（按 Rule 1）

---

## 文件命名

```
docs/retrospects/YYYY-MM-DD-{feature}-{type}.md
docs/retrospects/YYYY-MM-DD-{feature}-{type}.slides.md
```

**`{type}` 取值**：
- `retrospect` — 标准 N 轮迭代复盘
- `N-round-retrospect` — 强调具体轮数（如 `9-round-retrospect`）
- `retrospect-internal-share` — 内部分享导向，结构同标准但语气更外向
- `mockup-retrospect-internal-share` — mockup session 专属

---

## 8 段格式

每篇复盘都应包含以下 8 段（顺序固定，长度按 session 量级调节）：

### 1. TL;DR

- 总轮次 / 关键统计指标（轮数、文件改动、规则回流条数）
- 最终交付一句话总结
- **核心 insight**（一句话最关键反思，加粗 + blockquote 强化）

### 2. Session 概览

- **起点**：用户原始需求 / 客户场景一句话
- **最终落地**：核心 deliverable 列表（Figma 帧 / 文件路径 / artifact 清单）
- **Process 产物**：handoff doc / pickup doc / 规则回流条数 / phase0-ledger entries

### 3. 时间线（按用户 feedback 顺序）

5 列表格：

| # | 版本 | 用户 feedback 触发 | 改动量 | 性质 |
|---|---|---|---|---|

**写法要点**：
- 选 **5-15 个** turning points（不是全部）
- "用户 feedback 触发"列要写**用户原话**（带引号），不是 AI 的 paraphrase
- "性质"列归类：AI 过度解读 / AI 纪律 gap / 用户给参考后才纠正 / AI 资源复用弱 / 等

### 4. Top N Process Gap（按返工成本排序）

每个 Gap 一段，结构：

#### Gap N · **一句话总结**

**实证**：
- 具体哪几轮 / 什么决策错 / 用户哪句话点破
- 用引号附带用户原话

**返工成本**：N 轮 use_figma calls / N 文件批量改 / X 小时

**原因**（次重要）：用一句话指出 AI 行为模式的本质问题，不是 surface fix

**✅ 解决方案**（**最重要**，强制三段）：
- **当下修复**：这个 session 内具体执行的修复动作（改了什么文件 / 节点 / 哪些数值，可执行可验证，不是抽象描述）
- **长期防护**：抽象出来的规则 / 流程 / skill / 硬约束 — 让此类问题以后不再发生
- **真源落地**：✅ 已落 X 真源（具体文件路径）/ ⏳ 待回流到 Y，触发条件 Z

**为什么强制三段**：复盘只讲"问题 + 原因"没有价值 — 分享对象（团队 / 未来的 AI session）需要的是「**遇到同样问题该怎么办**」。当下修复证明问题已修，长期防护让规则成形，真源落地让规则跨 session / 跨 consumer 可被自动加载。三段缺一不可。

**N 取值**：
- 简单 session：3 个 Gap
- 复杂 session：5 个 Gap
- 极复杂多 session：可到 7-8 个，但单文件别超

### 5. 高效对话 N 条建议（按 ROI 排序）

**分 3 段**（强制）：

#### 给 UX / PM（提需求方）

教用户怎么写 PRD / 提需求让 AI 少走弯路

#### 给 AI 协作流程

教 AI 自己（或下次 session 的 AI）改行为模式

#### 给 PM / Stakeholder（review 方）

教 review 的人用什么 checklist / 怎么看物料

**写法要点**：
- 每条建议带**编号** (1) (2) ...
- 每条加**一句反例/正例**对比，更易吸收
- 建议跟 Gap 段呼应（Gap 暴露的问题 → 建议解决路径）

### 6. 规则回流清单

**两个子段**：

#### ✅ 已落回流（本 session 写入真源）

表格：规则 / 真源文件 / 简述

#### ⏳ 待回流（下 session 完成 / 等触发条件）

表格：规则 / 目标真源 / 触发条件（如"累积 3+ 同类 session 才考虑抽象到 design-process.md"）

**写法要点**：
- 明确写出真源文件路径（不只是规则 ID）
- 待回流条目要写**触发条件**，避免污染 TVU 真源（单次实证不够强）

### 7. Model 选型实证

固定 3 行表格 + 一段 Hybrid 推荐：

| 模型 | 适合场景 | 本 session 起作用时刻 |
|---|---|---|
| **Opus 4.7** | 主对话 / 架构推理 / 自审 / 跨文件回流 | 具体哪几个时刻发挥了 Opus 优势 |
| **Sonnet 4.6** | 执行 batch 改动 / probe / 简单 swap | 具体哪些步骤可委托给 Sonnet |
| **Haiku 4.5** | probe / 简单查询 | 不适合主对话 |

**Hybrid 推荐**：Opus 做 plan owner，Sonnet subagent 做 executor

可选：**纯 Sonnet 推算**段（如果全 Sonnet 跑本 session，估计返工率、漏问的关键问题等）

### 8. 给团队的 3 个 Action Items

每条结构：

**N. （Action title）**
> （为什么 / 期望影响）

**写法要点**：
- **3 个** action items（不多不少，强迫精简）
- 每条要有明确的目标 / 期望影响，不是 vague 的"改进"

---

## 文件尾部（可选附录）

可加：

### 附录 A · 改动统计

表格：改动类型 / 次数

### 附录 B · 关联文档

链接 handoff / pickup / 其它 session 的复盘

### 文末 metadata

```markdown
> **复盘人**：Claude {model} + {AUTHOR} (UX)
> **复盘时间**：YYYY-MM-DD
> **目标受众**：TVU 内部 — UX team + AI 协作流程改进
> **联系**: 真源文件全部在 `tvu-design-system` repo 内可查
```

---

## 长读版 vs Slides 版

每篇复盘**配对两份**（按 [[consumer-product-conventions]] Rule 1）：

| 版本 | 用途 | 段数 |
|---|---|---|
| `*.md` 长读版 | 精读 / handoff reference / gitea 浏览器渲染 | 全 8 段 + 附录 |
| `*.slides.md` Marp 源 | 内部分享投屏（PPTX 导出） | **重组为 15-20 张 slide**，不是 1:1 复制 |

**Slides 重组原则**：
- 一张 slide 一个 idea
- 表格行数压缩（长读版 17 行 → slide 5-8 行精选）
- 每段开 lead slide 做章节扉页
- 引用块强化 key insight
- 详见 `_template.slides.md` 骨架

---

## 反模式

| ❌ 反模式 | ✅ 正确做法 |
|---|---|
| 复盘只描述"做了什么"，不分析根因 | 每个 Gap 必含**原因**段，指出 AI 行为模式问题 |
| Gap 只写"问题 / 原因 / 回流"三段（回流偏 meta，缺当下修复 + 长期防护）| 必含 **✅ 解决方案** 强制三段（当下修复 / 长期防护 / 真源落地）— 复盘的最关键价值是"下次怎么办" |
| 时间线写 AI paraphrase 用户意思 | 写**用户原话**带引号，避免漂移 |
| 规则全归在"待回流"，不区分触发条件 | 待回流必写触发条件（如"累积 3+ session 才上 TVU 真源"）|
| 长读版和 slides 内容 1:1 复制 | slides 重组精选，不复制 |
| Action Items 写 5-10 条 | 强迫 3 条，逼出真正重要的 |
| Generic team 署名 | 用 git user.name（按 [[consumer-product-conventions]] Rule 3）|

---

## 标杆参考

**首版示范**：[`MicroApps/docs/retrospects/2026-05-20-video-sync-mockup-retrospect-internal-share.md`](../../../../../MicroApps/docs/retrospects/2026-05-20-video-sync-mockup-retrospect-internal-share.md)

这份是 2026-05-20 Video Sync mockup session 的复盘，结构完整、根因分析清晰、回流落点明确。写新复盘时**直接参考它的段落组织**。

**第二份参考**：[`MicroApps/docs/retrospects/2026-05-21-consumer-scaffold-marp-theme-retrospect.md`](../../../../../MicroApps/docs/retrospects/2026-05-21-consumer-scaffold-marp-theme-retrospect.md)

infra / tooling 类 session 的复盘示范（跟 mockup session 有差异：无 PRD、无 Figma 帧，但 8 段格式仍适用）。

---

## 演进策略

**改本格式 spec** → 改本文件 → 所有 consumer 下次写复盘时按新格式

**反模式**：在某个 consumer 单点改自己的 retrospect README 后失同步——本文件是真源，其它都是消费者。