# BRIDGE-MOCKUP-007 ROI Validation — v1/v2/v3 + 战略转向

> Date: 2026-05-27
> Status: BRIDGE-MOCKUP-007 closed (ROI gate PASS but redirects scope)
> Next: 新 entry BRIDGE-MOCKUP-008 — Figma 库全镜像 batch authoring（详见末尾 §下一步）

---

## 一句话

ROI gate 跑了 3 轮（共 32 题对照 + 1 轮真 Figma mockup），最终 PASS Δ=44pp。但**关键 finding 不在数字**——v3 暴露 BRIDGE-MOCKUP-007 真正解决的问题是"**mockup 一致性**"而非"语义正确"，且 SoT scope 应从 manifest（642）升到 **Figma 库全镜像**（~650+）。

---

## 三轮设计 + 数据

| 轮 | 测试集 | 路径 | A 结果 | B 结果 | Δ | 主要发现 |
|---|---|---|:---:|:---:|:---:|---|
| **v1** | 8 题 business句 ↔ registry slug 直接映射 | code-AI (text) | 8/8 | 8/8 | 0pp | 测试集 ceiling 过高，关键词字面对应 |
| **v2** | 8 题 name-naive 陷阱（business 句不含 slug 字面）| code-AI (text) | 8/8 | 8/8 | 0pp | manifest+registry 已编码 affordance 4 层：slug 前缀 / tags / generated 文件分组 / outline 后缀。code-AI path SoT redundant |
| **v3** | 同 v2 八题，但**真画到 Figma**，禁 code-side registry | mockup-AI (Figma) | 4.5/8 = 56% | 8/8 = 100% | **44pp** | SoT 在 mockup-AI path 真有价值，但 finding 更微妙（见 §finding 三层）|

### v3 详细评分

| T | 业务 | A 选 | B 选 | A 分 |
|---|---|---|---|:---:|
| 1 | 喜欢/最爱 | mark/**favorite on** | mark/star | 0.5 |
| 2 | loading | load/loading **2** | load/loading 1 | 0.5 |
| 3 | 主题切换 | **Setting/Switch** ⚠️ | Picture/picture-light | 0.0 |
| 4 | inline error | Message/Error **4** | Message/Error 1 (outline) | 0.5 |
| 5 | selected | Edit/Selected | Edit/Selected | 1.0 |
| 6 | legend 折叠 | Arrow/**Double up** | Arrow/Dropdown | 0.5 |
| 7 | help tooltip | Message/**Help 2** | Message/Info 1 | 0.5 |
| 8 | 三点 more | Menu/More | Menu/More | 1.0 |

(B 全 1.0 × 8 = 8.0)

详细 A/B 报告：
- v1: [`docs/internal/_prompts/archived/bridge-mockup-007-roi-v1.report.md`](../_prompts/archived/bridge-mockup-007-roi-v1.report.md)
- v2: [`docs/internal/_prompts/archived/bridge-mockup-007-roi-v2.report.md`](../_prompts/archived/bridge-mockup-007-roi-v2.report.md)
- v3: [`docs/internal/_prompts/archived/bridge-mockup-007-roi-v3.report.md`](../_prompts/archived/bridge-mockup-007-roi-v3.report.md)

---

## v3 Finding（三层）

### 层 1 — 现象

A path 56% / B path 100%。Δ=44pp 远超 PASS 阈值 30pp。

### 层 2 — 微观诊断（用户 ack）

A 失分分布：
- **T3 救场（0.0）**：TVU 库 `search_design_system` 对 sun/moon/theme/dark/light 全无命中 → A fallback Setting/Switch（语义偏离）。SoT 把 picture-light 的 synonyms 含"theme toggle / brightness"，B 一击命中。这是 **SoT 不可替代** 的 case
- **T2/T4/T6 variant precision（各 0.5）**：A 挑了同系列 sibling 但不是 SoT registered 的 variant（loading 2 vs 1 / Error 4 vs Error 1 outline / Double up vs Dropdown 单 chevron）。SoT 价值 = 选定 canonical variant
- **T1/T7（各 0.5，但 user 评 A 更好）**：A 找到 mark/**favorite** 和 Message/**Help**，**SoT 35-pilot 没有这两个**。user 确认 A 选的更直接、语义更准。这两题 A 失分**不是因为 SoT 帮 B，而是因为 SoT 漏了这俩 icon**

### 层 3 — 战略 finding（重新定义目标）

**SoT 不是 "AI 选对 icon 的数据库"**——v1/v2 证 code-AI 不需要，v3 T1/T7 证 mockup-AI 自由 search 在 SoT 漏项处反而更好。

**SoT 真正解决的问题是 "mockup 一致性"**——保证同一种业务意图（"喜欢"/"help tooltip"/...）在不同 mockup 任务、不同 AI session、不同时间点都收敛到**同一个 figma_component_key**。没 SoT 时 AI 各自找各自的（A 这次 favorite 下次 heart 再下次 star），mockup 视觉碎片化无法跨产品复用。

→ BRIDGE-MOCKUP-007 目标从 ~~"icon 语义数据库"~~ → **"mockup 一致性收敛器"**

---

## Scope hole 根因

35-icon pilot 是从 **manifest** 起手筛的（code 已用的 icon）。但：
- mockup 业务句会触达 **manifest 没收但 Figma 库有** 的 icon（v3 T1 favorite / T7 Help 实证）
- manifest 反映"代码已经用过"，Figma 库反映"设计师已经发布"——两者非镜像
- AGENTS.md §0 `FIGMA_AS_SOURCE_OF_TRUTH` 原则要求所有 code/SoT 层镜像 Figma；SoT 也应该
- **SoT scope 应从 manifest 升到 Figma 库全镜像**（~650+ published icon components）

---

## 战略调整 — Figma 库全镜像 + batch authoring

**撤回** v3 草案里 demand-driven trickle 方案（用户拒绝，理由"不集中、需要前期批量"）。

改 **Figma-库-全镜像 + 批量集中处理**，分 4 phase：

| Phase | 动作 | 估时 |
|---|---|---|
| **A** | 写 extract script：从 Figma 库拉**全部** published icon component（key + name + node_id + 必要 metadata），生成 batch authoring 工作清单（含 35 已有 entries 标识避免重复）| 0.5-1h |
| **B** | AI batch-author 剩余 ~615 entries：按 Figma 库 folder 分批（Edit/ / Arrow/ / Message/ / Menu/ / Picture/ / mark/ ...），每批 dispatch Codex fresh session，输出 affordance/synonyms/when_to_use/notes 候选含 🟡 marker | ~10-15h (~10-15 个 Codex prompt) |
| **C** | User batch-review：按 folder 一次审 10-15 个，accept 去 🟡 / reject 改候选 / flag 给 plan owner 重写 | ~5-8h（user 时间） |
| **D** | Sync 机制：扩 `pnpm sync:figma-library` 加一步对比 Figma 库新增/移除 icon vs `affordance-categories.json`，差异 → 候选 entry / 弃用警告 | 1-2h |

总估值：~17-26h 工程 + 5-8h user，分 1-2 周完成。

---

## 此次实验产出物 inventory

### Prompts (3 轮 × 2 路径 + 1 次 fix iteration)

- [v1 A](../_prompts/archived/bridge-mockup-007-roi-a-no-sot.prompt.md)（fix 后版本）
- [v1 B](../_prompts/archived/bridge-mockup-007-roi-b-with-sot.prompt.md)
- [v2 A](../_prompts/archived/bridge-mockup-007-roi-v2-a-no-sot.prompt.md)
- [v2 B](../_prompts/archived/bridge-mockup-007-roi-v2-b-with-sot.prompt.md)
- [v3 A](../_prompts/archived/bridge-mockup-007-roi-v3-a-no-sot.prompt.md)
- [v3 B](../_prompts/archived/bridge-mockup-007-roi-v3-b-with-sot.prompt.md)

### Reports

- [v1 report](../_prompts/archived/bridge-mockup-007-roi-v1.report.md)
- [v2 report](../_prompts/archived/bridge-mockup-007-roi-v2.report.md)
- [v3 report](../_prompts/archived/bridge-mockup-007-roi-v3.report.md)

### Figma artifacts

- Page `4531:3262` "Test 20260526" in MicroApps file `DtZcMkhNy6qh6jbQQnhreQ`
- `A-Path-V3-NoSoT` (node `4549:128`) at x=0
- `B-Path-V3-WithSoT` (node `4542:132`) at x=1200
- 17 icon instances（A 8 + B 9，B T1 双态）

### 配套副产出

- [figma-technical-reference Q13](../figma-technical-reference.md#q13-mockup-root-frame-sizing-默认-hug-contents-而非-fixed)（frame-overflow 防范条款）

---

## Lessons learned

### 1. ROI gate 设计本身需 baseline calibration
v1/v2 测试集 ceiling 过高（A 自己就 8/8），白跑 2 轮才意识到要换 path 而非加难度。**未来 ROI 类实验起手要先估 baseline——能否拿 0/8 是 5/8 是 8/8**。如果 baseline 接近天花板，实验本身没区分度。

### 2. 跨 path 验证不可省（code-AI vs mockup-AI）
SoT pilot schema 双消费者设计（code_ai + mockup_ai 双 binding）就是为 v3 这种发现量身定做的。**只跑一边等于只测一半**。

### 3. AI 自由 search 优于 SoT 时 = scope hole 不是 schema 问题
v3 T1/T7 A 选得更好，第一反应是"schema 不够好"——但根因是 35-pilot scope 漏。**schema 没坏，要扩 scope**。

### 4. user judgment 反转结论方向
我最初推 demand-driven，user 立刻指出"不集中、要批量、且 SoT 应镜像 Figma 库"。这个反推完全正确，把方案从 trickle 改成 batch + 全库镜像。**plan owner 要保持对 user 战略输入的开放，不要锚定第一推荐**。

---

## 下一步（BRIDGE-MOCKUP-007 close + 008 open）

1. **本 retrospect commit + push 后，BRIDGE-MOCKUP-007 视为 closed**（pilot 验证 + 战略调整完成）
2. **新建 BRIDGE-MOCKUP-008**：Figma 库全镜像 batch authoring (Phase A-D)。Backlog entry 见 [`backlog.md`](../backlog.md)
3. Phase A 起手 prompt 留到下次 session 设计——本 session 不动 batch 工作（context 已偏满）

---

## 相关 memory 更新

无新 memory 需写——本 retrospect 已 cover 所有 lesson；既有 memory 仍适用：
- [feedback_baseline-before-plan](baseline-before-plan) — ROI lesson #1 同源
- [feedback_one-shot-prompts](one-shot-prompts) — v1 误禁 icon-aliases.ts 是 prompt 设计 bug 同源