# V4-2259 Mockup 协作过程复盘（内部分享）

> 任务：V4-2259 Video Orientation / Aspect Ratio（LCD 文件 `0054ib` page `8790:2`）—— V3+V4 双设备设置页 + 拍摄×输出旋转/黑边输出矩阵 + PRD/UX 交付。
> 日期：2026-06-23 → 06-24 · 跨 2 日单 session · AI = Claude（plan owner）+ 多个 executor subagent。

---

## 1. TL;DR
- **总轮次**：~12 轮用户 feedback 纠偏（含 2 次语义级返工 + 1 次 scope 翻转 + 1 次版本号修正）。
- **最终交付**：V4/Pocket-only Aspect Ratio 设置页（含 landscape 9:16 禁用态）+ 4 个真实 Home 视图输出效果（竖拍 16:9 转90° / 9:16 黑边 × 1路·4路）+ canonical 6 段 PRD（需求来源 4 Jira 带超链接）+ 2 张 M23 UX 卡。机检全绿。
- **核心 process gap 数**：5 个，**4 个同源**——「规则/资产已存在但没在收尾前触发、或委派 subagent 时没写进执行 spec」（激活层失败）。
- **关键 insight**：本 session 几乎所有返工不是"不知道规则"，而是"规则没被激活"。委派 subagent 放大了这个问题——subagent 只做我 spec 里写的，没写进 spec 的既有规则（M23.8.1 Jira 遍历 / A-逐行 / design-walkthrough）就被跳过。

## 2. Session 概览
- **起点**：续跑 handoff §5（V3+V4 双设备 + 9:16/16:9 效果图 + 更新 UX/PRD）。
- **终点**：特性收敛为 **V4（TM1100, 软件 8.4）+ Pocket 设备 only**；效果图改为真实 Home 视图；PRD 重建 6 段 + 需求来源遍历 4 Jira。
- **Process artifacts**：handoff（含 scope 修正横幅）、work-log ×6、规范回流 commit（M23.8.1，已 push）、本复盘。

## 3. 主要迭代时间线
| # | 触发（用户 feedback）| 改动量 |
|---|---|---|
| 1 | 效果图语义误读①：以为是 LCD 屏换内容比例 | 删 home-9:16 重做 |
| 2 | 效果图语义误读②：实为输出画帧 + 旋转保全分辨率，且非 4 格 | 重建输出矩阵 |
| 3 | 规则收紧：横拍只 16:9 / 竖拍 9:16 有黑边 / Home=Receiver / 无确认弹窗 | 删确认弹窗 8803:2 + 矩阵改 3 情形 + 黑边 |
| 4 | "PRD 没按 6 段 + Jira 没列全 + 走查没发现" | PRD 重建 6 段 + 补跑 design-walkthrough（C1-C7） |
| 5 | "效果图用真实 1路/4路 Home 视图看" | 删抽象帧 + 建 4 Home 视图 |
| 6 | "需求来源覆盖全吗 / 超链接呢 / 双语样式呢" | 需求来源补 Jira + setRangeHyperlink + A-逐行 |
| 7 | "FB-9619 为什么没关联" | 补二度关联 Jira |
| 8 | scope 翻转："V3 不支持 Pocket、无竖屏拍摄" | 全页去 V3 → V4/Pocket-only |
| 9 | "怎么还有 V3 字样" | 彻底删 V3 解释句（之前误判保留）|
| 10 | "排期版本有误，应是 8.4" | V8.0+ → 软件 8.4（父 Epic） |

## 4. Top 5 Process Gap（按返工成本排序）
1. **收尾前没跑 design-walkthrough（F1）**（成本最高）：PRD 结构错 / confirm 冲突 / 去黑边 / 4 组合 一次性被用户抓出。规则早在（design-qa-loop / Delivery Gate），没触发。→ 回流落点：激活层，**Jira mockup 收尾前必跑 F1**（已记 handoff，属既有规则）。
2. **委派 subagent 时没把既有规则写进 spec**：PRD-rebuild subagent 没遍历 Jira issuelinks（M23.8.1 已存在）、没做 A-逐行（M23 §双语已存在）、没加 setRangeHyperlink。→ 回流：M23.8.1 已补「遍历到二度 + V4-2259 复发实证」（commit 87268b0b）；**新增纪律：委派 subagent 必把命中的 M-rule 写进执行 spec，不能靠"读了 Step B"**。
3. **交付物语义歧义没先确认就批量做**（×2 返工）：效果图语义误读 2 次。✅ 部分止损——home 9:16 用了"先建 1 样张给 owner 确认"，仅返工 1 帧。→ 建议固化：**语义歧义先建 1 样张 confirm 再批量**。
4. **AI 主观保留不该留的内容**：scan 抓到 V3 后，我自作主张保留"V3 无 Pocket"解释句 → 被用户二次抓。→ 教训：**清理类任务，命中即清，不替用户做"留作说明"的判断**。
5. **版本号凭假设填**（V8.0+）：未对父 Epic 核版本（实为 8.4）。→ 教训：**版本/排期以 Jira Epic 为准核对，不凭设备代号假设**。

## 5. 高效对话建议（按 ROI）
- **给 UX/PM（提需求方）**：① 交付物的「语义/范围/版本」起手一次说清（效果图=屏还是画帧 / 哪些设备 / 哪个软件版本），能省 2 次语义返工 + 1 次 scope 翻转；② 设备/版本约束最好直接给（V4+Pocket / 软件 8.4），AI 凭代号假设易错。
- **给 AI 协作流程**：① Jira 关联型 mockup 收尾**必跑 design-walkthrough**；② 委派 subagent 把命中规则写进 spec；③ 清理任务命中即清不主观保留；④ 语义歧义先建 1 样张确认。
- **给 PM/review 方**：复审入口给 Figma Section smart link；需求来源段应能一键点到所有相关 Jira（已实现）。

## 6. 已回流 / 待回流规则
| 规则 | 真源 | 状态 |
|---|---|---|
| M23.8.1 需求来源遍历 Jira 关联图到二度 + setRangeHyperlink | `mockup-conventions.md` | ✅ 已 commit+push（87268b0b）；本为既有规则，补「二度遍历」+ V4-2259 复发实证 |
| 委派 subagent 须把命中 M-rule 写进执行 spec | （激活层）| 🟡 待 owner 拍板是否立为显式纪律 |
| 收尾前必跑 design-walkthrough（Jira mockup）| design-qa-loop（已存在）| 激活层，已记 handoff |

## 7. Model 选型
- **plan owner（编排 + 判断 + 回写规则）**：用强模型（本 session Opus）——多轮语义纠偏 + 规则辨析（区分"缺规则"vs"激活层"）需要判断力。
- **executor subagent（Apply 既有 spec 的 Figma 写）**：可中档模型，但**spec 必须写死**（本 session 证明 spec 不全则既有规则被跳）。

## 8. 给团队的 action items
1. UX/PM：需求起手模板加「交付物语义 / 适用设备 / 目标软件版本 / 相关 Jira 全链」四项，减少 AI 假设。
2. AI 流程：Jira mockup 的 Delivery Gate 前置 design-walkthrough 设为硬 checklist。
3. 待 owner 拍板：是否把「委派 subagent 写规则进 spec」立为显式纪律回流真源。

**附录 · use_figma 改动统计**：本 session 约 20+ 次 use_figma 写（建 V3/V4 设置页 → 删 V3、建/重建输出矩阵 ×2、4 Home 视图、PRD 6 段重建、多轮文字纠偏 insert/delete）；机检最终全绿（integrity/overlap/typography/bilingual）。