# Rule Execution Discipline Gap — "AI 读了规则但不执行"

> Closure date: 2026-06-01
> Trigger: BM-1047 BM (Micro-App Token Portal Multi-Seat Subscription) Figma mockup session
> Same病灶 prior实证: 2026-05-20 Graphics Insertion v8 M31 auto-layout refactor (`_metrics/phase0-ledger.md`)

---

## 一句话总结

AI 起手协议要求"读 `mockup-conventions.md` + `design-process.md` 全文"——这一步执行了；但**接下来逐项把规则贯彻到产物中**这一步反复掉链。两次实证都是同一类病灶：**规则**已在 session 上下文里，**执行纪律**没跟上。回流为 `mockup-conventions.md` 新增 **M-DISCIPLINE umbrella**，强制用 TodoWrite 把规则 checklist 物化。

---

## 实证一：2026-05-20 Graphics Insertion v8（已 ledger 在案）

- 上下文：MicroApps Graphics Insertion dual preview 设计任务（PVW + PGM panel + Layer panel）
- 规则：`mockup-conventions.md M31` Auto Layout 默认（"先 auto-layout，找不到合适机制再退到 absolute"）
- 实际：v1–v7 整个 After frame 用 Frame + 绝对 x/y 定位
- 抓出方式：用户在 Figma 里手动改一个子元素，发现"改一处其它得手动重算"——返工成本指数级上升
- v8 refactor：47/58 frames 改为 auto-layout 嵌套树 (81% compliance)，11 absolute 全是 M31 合法 exception
- 根因（写进 ledger 原话引用）：

  > **M31 是 TVU 现存规则，v1-v7 整个违规** — 不是规则缺失而是 AI 起手读了规则但执行时没贯彻的纪律 gap。M31 原文："先 auto-layout，找不到合适机制再退到 absolute" 是默认顺序。Path-of-least-resistance 让我反复用 absolute 写代码（更直观、更快），但产物**用户在 Figma 里手动修改时痛苦**。

- 当时记录的 mitigation：

  > 建议下次 @TVU mockup session 起手协议**显式 echo "本次 layout 默认 auto-layout，M31 已加载"** 强提示自己。

- ⚠️ **该 mitigation 未制度化**——只是建议，没写进任何 enforceable 规则或 skill protocol。

---

## 实证二：2026-06-01 BM-1047 mockup（本次）

任务：Jira BM-1047 / 把 Micro-App token portal subscription UI 改造为 multi-seat 模式 / 在 Micro-Apps Figma 文件新 page 出 mockup。

`design-process.md § "完整产品需求设计流程（8 步，Jira 关联型 mockup）— 2026-05-27 新增"` 明确列出 8 步是 required。**起手协议已读全文**。

### 8 步执行情况

| 步骤 | 真源 | 本次走向 | 抓出方式 |
|---|---|---|---|
| ① Page 命名 | M45 | 起手写成 `BM-1047 Multi-Seat Subscription 20260529`（缺尖括号 + Title 不齐）❌ | 用户问"jira 的链接为什么没等到 PRD 里面"时附带发现 |
| ② Jira component + hyperlink | M23.8 | 起手画 PRD 时**完全没加** ❌ | 用户问"jira 的链接为什么没等到 PRD 里面？我记得我写过一个流程" |
| ③ PRD 写入 Figma | Pre-Phase 0 Step B | 做了 ✅（但触发是用户说"采用双语支持"才进入，不是主动） |
| ④ Phase 0 (M0) | M0 | 做了 ✅ |
| ⑤ Draw mockup | — | 做了 ✅（多轮 refactor） |
| ⑥ UX 交付注释 (state-label) | M23 | 全部 frame 画完后**没加** ❌ | 用户："UX 交付说明比较少，确认写完全了吗？" |
| ⑦ 流程连线 (M23.6) | M23.6 | **没画** ❌ | 用户："流程上目前是没有连线的" |
| ⑧ Walkthrough / audit | F1 walkthrough skill | 部分做了（靠 walkthrough 多轮捕捉问题） |

**8 步默认命中率 ≈ 3/8 = 37.5%。剩下 5 步靠用户提醒触发——返工成本（重排间距 / 重新定位 frame / 加 SECTION 包装等）累积明显。**

---

## 4 个共同根因

| # | 根因 | 描述 |
|---|---|---|
| 1 | **Skill 读 ≠ Skill 执行** | 起手协议要求读 `mockup-conventions.md` 全文，AI 读了；但没把 8 步当 enforceable checklist 在每个里程碑 self-check。读了规则不等于贯彻规则。 |
| 2 | **Atomic focus drift** | 用户每轮聚焦一个具体问题（"refactor License" / "fix stepper"），AI 顺着做。跨轮的 8 步整体 checklist 自然掉了。 |
| 3 | **TodoWrite 没用** | harness 多次提醒 use TodoWrite，AI 每次 ignore。其实正是这个工具能 surface "M23 deliverable 还没做"。**这是本次最关键的可观测信号被忽略。** |
| 4 | **完成定义偏窄** | AI 把"6 个 popup frame 都画对了"当成 ready-for-walkthrough；TVU 真源定义的 deliverable 是 **popup + state-labels + connectors + PRD + Jira link** 整套。8 步缺 5 步就喊完工。 |

---

## 抽象：跨实证的共性

| 维度 | 2026-05-20 v8 | 2026-06-01 BM-1047 |
|---|---|---|
| 被违规则 | M31 (Auto Layout 默认) | 8 步流程（M45 + M23.8 + M23 + M23.6） |
| 触发场景 | 复杂多元素 frame layout | Jira 关联型 mockup deliverable |
| AI 行为 | 起手读了 M31 → 执行时反复用绝对定位 | 起手读了 8 步 → 执行时跳了 5 步 |
| 抓出方式 | 用户手动改 Figma 痛苦反馈 | 用户走查时点出"UX 交付少 / 没连线" |
| 返工规模 | v1–v7 → v8 整体 refactor 47 frames | 6 frames + 6 state-labels + 3 connectors + section 重新间距 |

**统一表达**：AI 起手读了规则但执行时反复 path-of-least-resistance 跳步——规则在上下文里**消极存在**，没有**主动 enforce 机制**。

---

## 回流到 `mockup-conventions.md`

新增 **M-DISCIPLINE umbrella**（rule-level，hard rule）。详见对应 PR diff in `mockup-conventions.md`。要点：

- **触发**：起手协议执行完后、画第一个产品 frame **之前**
- **强制要求**：用 `TodoWrite` 把当前任务**适用**的所有规则编号物化成 todo list（每个 item 一个 rule ID + 一句话标题）
- **执行约束**：每完成一个 mockup 里程碑，对应 todo mark done；未 mark done 完前不准说 "ready for walkthrough / ready for handoff / 完成"
- **Acceptance**: handoff doc 必含 "Rule checklist: \[M0 ✅ / M23 ✅ / M23.8 ✅ / M45 ✅ / ...\]"
- **legacy stub**: 暂无（新规则）

---

## Action Items

| # | Item | Owner | Status |
|---|---|---|---|
| A1 | 在 `mockup-conventions.md` 新增 M-DISCIPLINE umbrella section | AI | ✅ (本 closure 内同步写) |
| A2 | 在 `tvu-design-mockup` skill 起手协议加 "Step 8.5: 跑 TodoWrite list 8 步" 强制指令 | AI / 用户拍板 | ⏳ 候选 |
| A3 | 在 `tvu-design-code` skill 同步加（code 任务同样有规则被读不执行的风险） | AI / 用户拍板 | ⏳ 候选 |
| A4 | M-DISCIPLINE 第 3 次实证出现时，把 todo list 模板化（per task type 预填默认 list） | 用户 | ⏳ 等下次实证 |

---

## 给团队的一条核心建议

**"读 rule" 和 "do rule" 是两件事。** TVU 已经有完善的规则系统，但 AI 在 execution path 上反复跳步。下次任何 Jira 关联型 mockup / code 任务，起手第一步**用 TodoWrite 把适用规则物化**，然后**按 todo 执行而非按"自己脑子里记得"执行**。

> Telemetry 信号：harness 提醒"use TodoWrite"出现 ≥3 次而未响应，就是这条 rule 触发但 AI 没自我 enforce 的报警。