# Retrospect — CANONICAL-011 D3 prompt §0.8 漏 `src/canonical/index.ts`（2026-05-13）

> **触发**：CANONICAL-011 Chart D3 执行完，verify `audit:published-vs-code` 仍显示 Chart `figma-only`（1 项），定位是 audit 读 `src/canonical/index.ts` 而非 `src/index.ts`，Codex 按 prompt 只改了后者，前者漏。
> **影响**：BRIDGE-MOCKUP-004 收尾多一步——手补 1 行 `export { default as Chart } from './Chart.vue'` 才让 audit 转绿。
> **修复**：commit [444406a2](https://github.com/NancyZeng0210/TVU-Design-System/commit/444406a2)。

---

## 1 — Root cause

D3 prompt §0.8「src/index.ts export 加 Chart」只点了**消费者 entry**（`src/index.ts`），漏了**canonical 层 re-export**（`src/canonical/index.ts`）。两个文件用途不同：

| 文件 | 用途 | 读它的人 |
|---|---|---|
| `src/index.ts` | 库 main entry（npm 装后 consumer 用）+ Vue plugin install | consumer，build/dist |
| `src/canonical/index.ts` | canonical 层 re-export aggregator | **`audit:published-vs-code`**（reads `export { default as X }` regex 提取 canonical 名）+ internal imports |

Plan owner（我）写 D3 prompt 时只想到 src/index.ts 是 export "终点"，忽略了 canonical/index.ts 是 audit 的真源依赖。Codex 按 prompt 字面执行无可指责——这是 plan owner 的 prompt completeness 责任。

## 2 — 一般化教训

**所有 canonical 新组件实现 prompt 必须更新的"export wiring" 集合**：

| # | 文件 | 增改内容 |
|---|---|---|
| 1 | `src/canonical/<Component>.vue` | 新建 wrapper |
| 2 | `src/canonical/index.ts` | **加 `export { default as <Component> } from './<Component>.vue'`** ← 历史最易漏 |
| 3 | `src/index.ts` | 加 `import` + `export { <Component> }` + `app.component('<Component>', <Component>)` |
| 4 | `playground/docs/navigation.ts` | `CanonicalPageId` union + `navigationGroups` entry |
| 5 | `playground/docs/DocsShell.vue` | `pageLoaders` 和 component map 两处 |
| 6 | `playground/docs/figmaFirstRegistry.ts` | record entry |
| 7 | `playground/docs/pages/<Component>Page.vue` | 新建 docs page |
| 8 | （如 layout 变了）`tests/visual/__screenshots__/*.png` | **cascade refresh 全部 baseline，非仅新 page** ← 同日另一漏（[F20 baseline cascade fix](https://github.com/NancyZeng0210/TVU-Design-System/commit/061a3e54)） |

**反模式自查**：写 export wiring 段时光列「`src/index.ts` 加 Chart」是 incomplete。完整说法是「加 export 到所有 4 个 export-wiring 文件：`src/canonical/Chart.vue` + `src/canonical/index.ts` + `src/index.ts` (3 处：import / register / export)」。

## 3 — Action: 给后续 canonical impl prompt 加 checklist

在下次 plan owner 写新 canonical（如 CANONICAL-007 Pagination 完整重做、或 v1.0 Phase 6.x）prompt 时，§0 必含本表格 §2「export wiring」清单，避免遗漏。

可以放在：
- 新加一个 `docs/internal/_prompts/_templates/canonical-implementation-checklist.md`（template，被其他 prompt 引用）
- 或保持 inline 在每个 prompt（更稳，模板抽象太早会脆）

**结论**：先 inline 进每个 canonical prompt 的 §0 export wiring 段。等 3 个以上 canonical impl 都 inline 后再考虑抽 template（OK 抽象，遵循 CLAUDE.md "三似 better than premature 抽象"）。

## 4 — 同日 layout cascade lesson 复用

[F20 baseline cascade fix](https://github.com/NancyZeng0210/TVU-Design-System/commit/061a3e54) 修了同类「prompt incompleteness」漏洞 — D3 §2.13 只点「新 page 截 baseline」漏「所有现有 page baseline 需 refresh 因为 nav 加了 entry」。两个 lesson 共性：

> **Layout-affecting changes（nav / shared shell / page lattice）** 触发 **cascade**——影响远超本任务直接动的文件。Plan owner 写 prompt 必须穷尽列 cascade 边界（base impl + canonical wrapper + index re-exports + nav wiring + DocsShell + page + baseline + audit data sources），不能只列「主线」文件。

## 5 — 这条 retrospect 怎么被读到

下次 plan owner 写 canonical 实现 prompt 时：
1. 起手必读 STATUS.md → 第 3 项 `_plans/next-session-pickup-*.md`（如有指向）
2. 看相关 backlog entry（如 CANONICAL-007）
3. **应 grep `docs/internal/retrospection/*canonical-impl*` + `*prompt-gap*` 看历史教训**（不在协议里，建议加进 META checklist）

如要更机械触发：把 §2 表格直接写进 [`docs/meta-rules.md`](../meta-rules.md) 的「Audit/数据产出类 prompt 子规则」段或 AGENTS.md 必读链路第 6 项后面。但那是更大动作，本次先存档此 retrospect。