第 1 次失敗是運氣、第 2 次失敗是訊號。 同一個問題、同一個方向、同一類錯誤出現第 2 次時、停下來把處理層級升一階 — 不要繼續用同層方法第 3 次嘗試。第 1 次失敗的資訊不足以判斷「這條路是否值得繼續」、第 2 次提供「在同類條件下重複失敗」的證據、值得付出升級成本。

為什麼是 2 次、不是 1 次或 3 次

1 次失敗的資訊量不足

第 1 次失敗時可能的原因：

第 1 次失敗無法區分這四種 — 證據量不夠做決策。預設用最便宜的應對（修細節重試）是合理的。

2 次失敗的證據量足夠

同方向第 2 次失敗、四種原因中三種被排除：

第 2 次失敗 ≈ 「路徑本身有問題」的證據。繼續用同層方法第 3 次嘗試 = 忽略這個證據。

3 次以上是浪費

到第 3 次嘗試還沒升級、表示已經錯過訊號。每次失敗的學習回報遞減、執行者的耐心遞減、心智負擔累積。事後檢視常常會發現：「第 2 次就該停了、第 4 次才停浪費了兩輪」。

為什麼不是 1 次就升級

預防式升級成本太高 — 大部分問題第 1 次嘗試就解決。如果每次失敗都立刻升級、會在「修個 typo 就好」的場景過度反應。門檻定在 2 = 不過度反應、又不錯過真訊號。

三個應用面向

「2 次門檻」不是單一規則、是一條跨層級套用的元規則。三個典型升級方向：

應用 1：推理 → 量測（#11 在開發循環裡早一點用 playwright）

情境：CSS 行為跟預期不符、靜態推理該怎麼改。

升級：停止靜態推理、用 playwright browser_evaluate 直接讀 live DOM。把「四個變數（CSS / DOM / 繼承 / framework）」中假設的部分變成已知。

應用 2：手動驗證 → 自動化測試（#15 用前端測試把排版問題自動化）

情境：版型 bug 已經 debug 過、未來是否會回歸。

升級：把手動「改 CSS → 開頁面看」的驗證迴圈、換成 playwright 測試。下次有人改 CSS 立刻紅、不用人記得回歸驗證。

應用 3：同方向嘗試 → 換思路（#20 同方向反覆失敗的轉折點）

情境：用 grid 解某個 layout 問題、第一次沒解決。

升級：從「同層 retry」升到「換思路」。第 2 次失敗的訊號是「底層假設可能錯」、不是「再調一次參數就行」。

識別「同方向」：避免誤判 2 次門檻

「2 次失敗」必須是同方向才算門檻。誤判同方向會錯誤觸發升級、誤判不同方向會錯過真訊號。

同方向的判準

判讀問題：「兩次嘗試的差異、有沒有挑戰底層假設？」

• 沒有 → 同方向、第 2 次失敗 = 升級訊號
• 有 → 不同方向、相當於兩次第 1 次嘗試、繼續嘗試合理

反例：誤判為同方向

第 1 次：用 grid-row: 1 把 drawer 放到第一列、失敗 第 2 次：用 grid-row: 1 / span 2 跨兩列、失敗

兩次都基於「drawer 是 grid item」的假設 — 是同方向。第 2 次該停下來檢查這個假設（drawer 實際是 form 子節點、不是 grid item）。

反例：誤判為不同方向

第 1 次：寫 CSS 試 第 2 次：寫 JS 試（覺得「這算換工具」）

但兩次都基於「drawer 在 grid 第一列」的目標 — 假設沒變、只換了實作工具。仍是同方向。

不該套用 2 次門檻的情境

這條原則有適用範圍、不是所有失敗都套用：

核心判準：升級成本 vs 繼續嘗試成本的比較。當每次嘗試都很貴（人類幾分鐘 / 來回溝通 / 上下文切換）、2 次就該升級；當嘗試很便宜、可以放寬到 3-5 次。

內在屬性比較：四種失敗回應

推薦：第 2 次失敗升級。例外情境（探索 / flaky）顯式判斷再放寬。

跨情境辨識訊號表

下次工作中看到這些訊號、回想「2 次門檻」：

通用形式：「再做一次同方向的 X」第 2 次出現 = 該升級的訊號。

對應的實作篇

每篇示範這個原則的不同面向、各自展開具體場景：

讀的時候從本篇出發、依場景挑實作篇 — 不需要逐篇讀完。

判讀徵兆

核心原則：失敗的價值在於提供資訊。第 1 次失敗資訊不足以決策、第 2 次失敗資訊足以決策 — 兩者要用不同方式回應。混為一談會讓人在錯方向裡無限重試、或對小錯過度反應。

第 5 個面向：驗收訊號 — 「畫面對一次」是低資訊量訊號、跟「程式跑通一次」「測試過一次」是同類錯誤。詳見 #56 視覺完成 ≠ 功能完成 把驗收訊號的時間軸跟 2 次門檻接起來、#68 驗收的時間軸：四個 checkpoint 把驗收分散到多個時點。

第 6 個面向：測試訊號 — 「測試 PASS 一次」是低資訊量訊號（測試本身可能有 bug、可能太寬）。要 RED → GREEN 兩個訊號 — 一次 fail 一次 pass — 才能相信測試真的會 catch。詳見 #69 Test-First：先看到 RED 才相信 GREEN。

第 7 個面向：跨檔 emergence 訊號 — 在批量寫作 / 批量產出情境下、「第 2 次」要區分 同檔 vs 跨檔 兩種強度。同檔同 pattern 第 2 次出現 = 直接訊號、立即升級；跨檔同 cadence 第 2 次出現 = 弱訊號、樣本數通常要到 5-10 才強到 catch。對應 #122 Cadence 同質化是模板的隱形維度 跟 #124 Emergence-class 違規規則化不了 — 跨檔 emergence 的 2 次門檻不在「寫第 2 篇就 catch」、而在「寫到 batch 進度 10-20% 時抽樣 catch」、過了這位置修正成本就會 N 倍上升。

「最小必要範圍」是 sanity 防線、不是優化選項。 縮 selector / observer / DOM 操作的範圍、目的不是為了讓程式跑更快、是為了讓行為可預測：不誤命中、不過度觸發、不被未來頁面結構變動打破。從具體放寬比從寬泛收緊容易得多 — 兩者的成本曲線完全不對稱。

為什麼是「sanity 防線」、不是「優化」

兩個概念常被混為一談

「縮範圍」聽起來像效能優化（少做一點工 = 快一點）— 這誤解掩蓋了它真正的價值。

把「縮範圍」當優化的後果：以為「現在沒效能問題、之後再縮」 — 但 sanity 防線錯過了第一行就追求的時機、未來補救成本更高。

寬範圍的代價不是「慢」

寬 selector / observer / 操作範圍的失敗模式：

四種代價都不是「慢」 — 都是「行為不可預測」。Sanity 防線守的是這個。

「從具體放寬」vs「從寬泛收緊」的不對稱性

兩個方向在表面上對稱、實際成本曲線完全不對稱：

從具體放寬（推薦）

1寫第一版：用最具體的 selector / 最小的 observer 範圍 / 最窄的操作邊界
2↓
3發現某個 case 沒覆蓋
4↓
5顯式評估「該放寬到什麼程度」
6↓
7擴大範圍、知道擴大後的影響範圍

每次擴大都是顯式決定 — 知道「我為什麼擴大、擴大到哪」。

從寬泛收緊（反推薦）

1寫第一版：用最寬的 selector / subtree observer / 全頁面操作
2↓
3某天發現某個 bug（誤命中、過度觸發、framework 衝突）
4↓
5不確定哪些地方是「故意要寬」、哪些是「意外寬了」
6↓
7試著縮、可能漏掉某些故意要寬的場景、引發新 bug

收緊時面對的問題：寬範圍的程式碼裡看不出「哪些是故意寬、哪些是意外寬」。原作者也不一定記得當初為什麼寫寬。

不對稱性的根源

這個不對稱不是工程偏好、是資訊量的差異：

• 從具體放寬：每次擴大時、有當前需求當證據（「為了 X case 才擴大」）
• 從寬泛收緊：縮的時候、不知道原本依賴哪些寬範圍特性

寫程式時的「具體 → 寬泛」走法保留了決策軌跡；「寬泛 → 具體」走法丟失了軌跡。

三類範圍的共同骨架

「最小必要範圍」原則跨三類獨立議題：

三者表現不同、機制不同、但底層都是同一條原則的應用 — 越寬越脆弱、越具體越穩定。

共通的設計工具

跨三類議題、設計「最小必要範圍」的工具有共通模式：

每個議題都有「起點 / 深度 / 過濾」三維度可顯式設計 — 同樣的設計骨架在不同情境重現。

應用辨識訊號

下次工作中、看到這些訊號該想到「最小必要範圍」：

不該套用「最小必要範圍」的情境

這條原則有適用邊界、不是所有「縮」都有意義：

核心判準：「最小必要範圍 = 滿足當前需求的最窄範圍」 — 不是極致最小、是「不再小就會漏」的點。盲目縮到「比需要還小」會犧牲覆蓋率、是另一種錯誤。

跟「2 次門檻」的協同

#42 2 次門檻 處理「失敗第 N 次該換策略」、本原則處理「第一次設計時範圍該多大」。兩者方向互補：

• 2 次門檻：失敗發生後、何時該升級處理層級
• 最小必要範圍：寫第一版時、就該追求 sanity 防線

如果第一版就遵循「最小必要範圍」、後續觸發 2 次門檻的機率會降低 — sanity 防線是預防、2 次門檻是補救。

對應的實作篇

每篇示範這個原則在不同議題的應用：

讀的時候從本篇出發、依議題挑實作篇。

判讀徵兆

核心原則：最小必要範圍守護的是「行為可預測」 — 寫的時候多想一點、debug 時少痛一點。寬範圍的代價不是慢、是出錯時定位困難 — 這也是為什麼這條原則在「沒效能瓶頸」的情境下仍然成立。

延伸到 stream 操作：#64 Feature 操作要跟 Source 同層合成 是本原則在 stream 領域的應用 — 「合成位置」就是「操作的範圍邊界」、選錯位置 = 範圍錯。寬範圍便利、窄範圍對齊、兩者反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

同一個值的權威來源只能有一個位置。 「位置」可以是 CSS selector、可以是定義機制、可以是函式 — 重點是讀者能明確指認「這個值的真相在哪」。多個來源會在時間維度上分歧、漏改、debug 時不知道哪個生效。SSoT 不是潔癖、是維護性的物理基礎。

為什麼多源會 drift

時間維度的失敗模式

寫程式的當下、多源沒問題 — 兩個值剛寫進去都是 64px、看起來一致。問題出在後續：

多源的隱形成本在時間維度累積。寫的當下看不出問題、是因為當下還沒分歧。

寫程式時的觀察盲點

寫多源的人通常不是不知道 SSoT 原則、是沒意識到自己在寫多源。常見盲點：

辨識自己寫多源、需要主動的 sanity check：「這個值的真相在哪？只有一個答案嗎？」

Fact vs Derivation 的區分

SSoT 適用對象是值、但不是所有「值」都該 SSoT — 區分兩種：

例子（CSS）：

 1/* Fact — 設計決定 */
 2:root {
 3  --search-title-h: 64px;        /* H1 高度是設計選擇 */
 4  --search-form-h: 68px;         /* form 高度是設計選擇 */
 5  --search-gap: 20px;            /* 間距是設計選擇 */
 6}
 7
 8/* Derivation — 從 fact 計算 */
 9.scope-position {
10  top: calc(var(--search-title-h) + var(--search-form-h) + var(--search-gap));
11  /* 不該寫 152px、那是 derivation 重複了 facts */
12}

把 derivation 寫成具體值（152px）= 把 fact 在 derivation 裡再宣告一次 = 多源。

區分 fact / derivation 的判讀問題

寫一個值時自問：「這個值是設計選擇、還是從別的值算出來的？」

• 設計選擇 → fact、找住址定義
• 從別的值算出來 → derivation、用 calc / function 表達、不寫具體數字

混淆兩者會固化多源 — 把 derivation 寫成數字、未來 fact 改了 derivation 不會跟著改。

三類 SSoT 違反

跨 #3 / #26 / #27 的三類具體表現：

違反 1：定義位置散落（住址多源）

同一個值在多個 selector 重複定義：

1/* 散在三處 */
2:root           { --search-title-h: 64px; }
3body.page-search { --search-form-h: 68px; }
4.search-shell   { --search-gap: 20px; }

不是錯、但維護者要 grep 才知道哪些值在哪、改的時候容易漏掉某處。

解法：定義集中在「跟使用範圍最匹配的最高層 selector」、其他地方只 var() 引用。

對應實作：#26 CSS 變數定義位置統一。

違反 2：來源機制混搭（機制多源）

同一個值有多種「取得方式」並存：

1// 對齊基準上四個值、其中三個寫死、一個量測
2--search-title-h: 64px;            // 寫死
3--search-form-h: 68px;             // 寫死
4--search-gap: 20px;                // 寫死
5--search-scope-h: ResizeObserver;  // runtime 量測寫回

寫死值依賴的渲染條件變了（字型、theme、scale）— 量測值會跟著變、寫死值不會、兩者錯位。

解法：選一邊走到底。內容靜態 → 全寫死；內容動態 → 全量測。混搭就是多源。

對應實作：#27 runtime 量測模式統一。

違反 3：對齊基準的真相分散（語意多源）

對齊問題本質是「方程組」 — 每個參與對齊的值都是基準的一個分量。任何一個分量值不確定、整個基準都靠不住。

1問題：filter padding-top 對不準 H1 + form 下緣
2分量：H1 (64px) + form (68px) + gap (20px) = 152px
3若任一分量是「我估的」、整個 152px 就不可信

解法：每個分量都要有明確的「真相位置」 — 寫死的 token 或 ResizeObserver 量測寫回變數、二選一。沒有「估算」這個選項。

對應實作：#3 視覺對齊用單一真實來源。

設計工具

1. 定義集中、引用分散

1body.page-search {
2  /* 集中定義 */
3  --search-title-h: 64px;
4  --search-form-h: 68px;
5}
6.search-shell .pagefind-ui__drawer {
7  /* 分散引用 */
8  margin-top: calc(var(--search-title-h) + var(--search-form-h));
9}

「集中定義」= fact 一個住址；「分散引用」= derivation 不重新宣告 fact。

2. 命名前綴標明範圍

1--token-*           /* 全站 design token */
2--page-search-*     /* 搜尋頁專用 */
3--pagefind-ui-*     /* 組件 hook */

前綴讓維護者一眼看出值的「歸屬」 — 改的時候知道影響範圍、不會誤改別處。

3. JS 寫入跟 CSS 定義同 selector

1body.page-search {
2  --search-scope-h: 60px;  /* fallback */
3}

1document.body.style.setProperty('--search-scope-h', h + 'px');
2// 寫到 body.style、跟 CSS 定義同 selector、cascade 一致

JS 寫入位置跟 CSS fallback 在同一 selector — 兩套機制保持一致來源。

4. 用 calc 表達 derivation、不寫具體數字

1/* 好 — derivation 用 calc */
2.scope-position { top: calc(var(--a) + var(--b)); }
3
4/* 較差 — derivation 寫具體數字 */
5.scope-position { top: 152px; }  /* 152 是 a + b 算出來的、現在固化在這裡 */

calc 把 derivation 顯式表達 — 未來 fact 改了、derivation 自動跟上。

不該套用 SSoT 的情境

跟其他原則一樣、SSoT 也有適用邊界：

核心判準：多源是不是「同一 fact 的多份拷貝」？是 → 違反 SSoT；不是 → 各自是獨立 fact、不違反。

跟其他抽象原則的關係

#43 最小必要範圍 處理「範圍越窄越穩定」、本原則處理「值的住址越唯一越穩定」。兩者方向不同、目的相同 — 都是讓行為可預測：

• 最小必要範圍：縮影響範圍、避免誤命中
• SSoT：縮值的來源數、避免分歧

兩者經常同時出現：縮 selector 範圍時、selector 本身的定義也該 SSoT（避免散在多處）。

對應的實作篇

每篇示範這個原則在不同議題的應用：

讀的時候從本篇出發、依議題挑實作篇。

判讀徵兆

核心原則：SSoT 守的是「未來改值時、知道改哪裡」 — 寫的時候多想一秒、未來改的時候少痛半天。多源是時間維度的隱形成本、寫程式當下看不出來、是因為時間還沒到。

延伸到 stream 操作：#64 Feature 操作要跟 Source 同層合成 是本原則在 stream 領域的應用 — 在下游做 filter / sort = 等於建了個第二定義（subset 上的「filter 結果」）跟 stream 全集競爭、是另一種形式的 SSoT 違反。多源便利（就地寫個值）、單源對齊（找 fact 位置）— 這個反相關的更高層原則見 #67 寫作便利度跟意圖對齊反相關。

延伸到 UI state：#70 URL 是 stateful UI 的儲存層 是本原則在「可分享 state」的應用 — URL 是該類 state 的 SSOT、不寫 URL = state 多源（in-memory + 使用者期望的 URL 但實際不存在）。

客製外部組件的穩定性與「離組件作者保證的對外介面多遠」成反比。 客製貼著介面做、跟組件作者站在同一邊、組件升級時客製不會打到；客製挖到組件內部實作、跟作者每個版本對抗、依賴前提隨時可能崩潰。理解四層的代價差異、是「跟外部組件合作」這件事的工程基礎。

為什麼有「層次」這個概念

組件 = 對外契約 + 內部實作

任何外部組件可以分成兩部分：

對外契約是「跟使用者的合約」、內部實作是「達成契約的手段」。客製貼著契約做 = 在合約範圍內、作者會維持；挖內部 = 跨越合約、作者沒義務維持。

「層次」反映依賴強度

從合約走向內部、依賴強度遞增：

1最穩 ─────────────────────────────────────────── 最不穩
2介面層 → 鄰接層 → 邊界內 DOM → 內部邏輯

不是「能不能做」、是「做了之後依賴什麼會不會變」。介面層依賴公開契約（穩）、內部邏輯依賴 source code（隨時變）。

四個層次

第 1 層：介面（最穩）

內容：組件作者公開設計的客製機制。

• CLI flag（如 --root-selector）
• Props / config（如 pageSize: 10）
• CSS variable hook（如 --component-color）
• 官方提供的 event / callback

穩定性：作者保證跨版本（minor / patch 升級不 break）。

例：Pagefind 的 --root-selector main — 用作者設計的索引邊界客製。

升級成本：通常零 — 作者改實作不影響介面。

第 2 層：鄰接（半穩）

內容：組件邊界元素的可辨識特徵 — class name、id、CSS reset 邊界。

穩定性：作者通常維持、但不像介面那麼正式。Major 版本可能改名。

例：Pagefind 的 .pagefind-ui--reset class 邊界 — 不是官方介面、但 .pagefind-ui 這個 class 名相對穩定。

升級成本：低-中 — class 改名才會打到、通常會在 release note 提及。

第 3 層：邊界內 DOM（不穩）

內容：組件內部的 DOM 結構、framework 生成的 hash class、子節點的相對位置。

穩定性：隨 framework 渲染週期 / 版本變動。

例：Pagefind 的 .svelte-yyy hash class、.pagefind-ui__drawer 在 form 內部的層級結構。

升級成本：高 — framework 升級可能立即打破。

第 4 層：內部邏輯（最不穩）

內容：組件 source code 的行為、private function、內部 state 流。

穩定性：完全不保證。

例：fork 組件改一個 function、monkey-patch 一個 private method。

升級成本：每次升級都要重新 merge / patch。

每往內一層的代價

四個維度全部隨層級遞增。沒有「往內推一層、某個維度反而變好」的情境 — 完全單向。

為什麼工程師仍會挖內部

知道有代價、為什麼仍會挖？通常因為：

挖內部的真實成本在升級時顯現、寫的當下看不出來。

三類常見的「想做但成本高」情境

情境 A：覆寫組件 specificity

組件用 hash class（.x.svelte-y.svelte-y）把 specificity 拉到 30、自家 CSS 蓋不過。

第 3 層做法（不穩）：寫 .x.x 雙寫、加 !important、跟組件 specificity 對抗。

跳出層級的做法：用 CSS Layers 把組件 CSS 包進 layer、自家 CSS 留 unlayered — 跳出 specificity 線性比較戰場。

對應實作：#24 CSS Layers 取代 specificity 戰。

通則：當「往內挖」會無限升級成本、找「跳出比較維度」的機制（layers / shadow DOM / portal）。

情境 B：在 framework 管的 DOM 內注入元素

想在組件內部塞一個自家 UI element — framework 重繪時清掉、需要 observer 補打、跟渲染週期競爭。

第 3 層做法（不穩）：注入 + observer 補打 + 跟 framework re-render 賽跑。

留在邊界外的做法：把客製 UI 留在 framework 邊界外、用 CSS（absolute、margin spacer）控制視覺位置 — 不進入 framework 的 children list。

對應實作：#5 與 framework-managed DOM 共處。

通則：客製跟 framework 各自有 DOM 邊界、要共存就用 CSS 控制位置、不要互相侵入。

情境 C：覆寫深度成本累積

要做的覆寫需要對抗 UA + 跨瀏覽器 + framework 三層、寫 5+ 條 CSS 才完成、改善的 UX 價值小。

第 3+4 層做法（不穩）：硬寫到底、最後產出脆弱客製。

事先告知 + 接受原設計的做法：開工前報告成本（需要寫多少、跨多少瀏覽器、有什麼殘留風險）、讓決策者用「成本 vs 改善價值」判斷。常常結論是「接受原設計」。

對應實作：#19 覆寫深度的成本告知。

通則：客製深度要事先評估、不要默默承擔。「接受原設計」是合理選項。

設計工具

工具 1：邊界辨識先於改動

寫客製之前、先列出組件提供的邊界：

1組件邊界清單：
2- 索引邊界：--root-selector （介面層）
3- 重置邊界：.pagefind-ui--reset class （鄰接層）
4- specificity 邊界：svelte hash class （邊界內 DOM 層）
5- 樣式 hook：CSS variables （介面層、若有）

對應每個客製需求、找最外層能滿足的邊界 — 介面夠用就用介面、不夠才推到鄰接、再不夠才考慮邊界內。

工具 2：跳維度的機制

當「同層對抗」會無限升級、找「跳到不同維度」的機制：

跳維度通常是一次性設計成本、之後免疫於同層的累積成本。

工具 3：覆寫成本告知 protocol

開工前評估三個累積層：

任一層需要對抗、把成本攤開讓使用者決定值不值得做。

何時接受原設計、不打覆寫戰

「接受原設計」常被當作放棄、實際上是評估後的合理選擇。判讀條件：

四個條件中三個符合 — 強烈建議接受原設計。

不該套用「貼著邊界」的情境

這條原則有適用邊界、不是所有客製都能停在介面層：

核心判準：這個客製要跟組件升級共存嗎？ 是 → 貼邊界；否 → 怎麼做都行。

跟其他抽象原則的關係

跟外部組件合作的設計、通常需要同時應用多條原則。

對應的實作篇

每篇示範這個原則在不同情境的應用：

讀的時候從本篇出發、依情境挑實作篇。

判讀徵兆

核心原則：跟外部組件合作的工程基礎是「層次認知」 — 先辨識能做的範圍、選最外層能滿足需求的位置、跳維度而非同層對抗、必要時接受原設計。「組件不能客製成這樣」常常是「該層做不到、要往外或跳維度找」、不是真的不能。

跟 #59 Filter × Source 合成策略 同構：本卡的「四層合作」跟 #59 的「五策略」都是「離 source 公共介面越近、合作越穩」— 介面層 ≈ 推進 query (A)、邊界層 ≈ 多 index (C)、邊界 DOM ≈ 自動續抓 (B)、內部結構 ≈ 接受 D / E。同個原則套用在「客製 UI vs 客製 filter」兩個情境。

寫程式時最容易寫出的版本、通常是離意圖最遠的版本。

兩個方向反相關 — 越容易寫、越容易錯位。識別這個反相關 = 識別自己正在掉進「容易寫的陷阱」、不是寫出對的東西。

為什麼便利度跟正確性反向

便利度的來源

寫程式當下、能「快速寫出」的條件是：

• 手邊已經有需要的資料（已 fetch、已 render、已 materialize）
• 現成的 API 能直接呼叫（document.querySelectorAll、Array.from、results.filter）
• 不需要跨抽象層（不用回到 source / framework 邊界 / build pipeline）

這些條件都建立在「已是 subset / 已展開 / 已下游」的位置 — 因為下游才有「現成上下文」。

意圖對齊的代價

「跟使用者意圖對齊」的條件相反：

• 操作 stream 全集（不是 subset）
• 在 source 層處理（不是 view 層）
• 處理 build-time 抽象（不是 runtime 取巧）

這些條件要求回到上游 / 跨抽象層 / 處理沒被 materialize 的東西 — 而上游沒有「現成上下文」、需要刻意建立。

反相關的本質

便利度 = 用已有資訊；意圖對齊 = 處理還沒有的資訊。資訊狀態相反 → 兩個目標反相關。

「容易寫」這件事本身就是「在錯位的層」的徵兆。不是「容易寫的有時候錯」、是「容易寫的多半錯」。

多面向：跨領域的同個結構

面向 1：Filter 在 view 層（#55 的 case）

容易寫：document.querySelectorAll('.result').forEach(el => el.hidden = !matches(el)) — 5 行、用現成 DOM。

意圖對齊：把 filter 推到 source 層（#61）— 改 SDK 呼叫、可能改 build。

「為什麼層錯位的 bug 容易寫出來」見 #55 Filter 與 Source 的層錯位。

面向 2：Selector 用過寬範圍

容易寫：document.querySelectorAll('.title') — 一行命中所有 .title。

意圖對齊：document.querySelector('.pagefind-ui').querySelectorAll(':scope > .results > .result > .title') — 起點 + 範圍 + 過濾顯式設計（#14 / #43）。

過寬 selector 的代價是「命中無關元素 → 副作用未知」 — 但寫的時候不會看到。

面向 3：Inline style + !important

容易寫：el.style.setProperty('display', 'none', 'important') — 立刻生效。

意圖對齊：el.classList.toggle('is-hidden') + CSS class（#28）— 樣式留 CSS、JS 只 toggle state。

Important 是「立刻生效」的便利、代價是「DevTools 看不出為什麼」、改視覺要 grep 多處。

面向 4：Middleware filter（後端 case）

容易寫：在 API response 後加 filter middleware — 對 response array 做 .filter()。

意圖對齊：把 filter 推進 ORM query / SQL WHERE — 改 query、可能加 index。

Middleware 在 pagination 之後、漏掉沒在這頁的符合項（#64）。

面向 5：Cached subset 上算統計

容易寫：stats.average = cache.values().reduce(...) / cache.size — 直接用 cache。

意圖對齊：先 revalidate、再算；或標明「statistic on cached subset」（#66）。

Cache subset 算出的統計跟 fresh dataset 算出的不同、但寫的時候看不到差異。

五個面向共用結構：用「已存在的東西」5 行解決、產出對「沒處理到的東西」silent 失敗的版本。

便利度的時間維度：當下便利 vs 未來便利反向

便利度有兩個尺度、方向相反：

「五年後讀 code 的人」包括五年後的自己 — 那時候不會記得當下為什麼選 view 層 filter、只會看到「為什麼這個 filter 漏掉了沒載入的東西」。

為什麼兩個尺度反向

當下便利的條件是「用已存在的東西」：

• 已 materialize 的資料（不用追上游）
• 已存在的 API（不用設計介面）
• 已有的命名（不用想新名字）

未來便利的條件是「留下可預測的結構」：

• 操作位置跟意圖對齊（不用 debug 為什麼結果怪）
• 抽象層清楚（不用穿三層才理解一行）
• 命名反映意圖（不用讀 commit history 才懂）

兩個條件方向相反 — 用已存在的東西 = 順著當下慣性；留下可預測結構 = 抵抗當下慣性、為未來付出。

「我等下會 refactor」是個謊言

寫便利版時內心 OS 常常是「先這樣、晚點 refactor 補回來」 — 但補回來這件事在實務上幾乎不發生：

• Refactor 沒有功能訊號驅動（壞掉才修、能用不修）
• 重新理解當時為什麼這樣寫、需要把整個 context 重建一次（成本反而高）
• 寫的時候的決策已經影響了周邊代碼（要 refactor 一處要連帶改五處）

所以「現在便利、未來再對齊」這個 plan 實際上是「現在便利、未來繼承這個錯位」。當下的選擇就是長期的選擇、沒有「之後補」這個選項。

要嘛當下對齊、要嘛接受 #66 explicit 縮小 把限制攤開。沒有第三條路。

識別訊號：什麼時候你正掉進這個陷阱

訊號 1：「這樣寫最快」

內心 OS「直接 forEach + filter 就好」「就用現成的 API 啊」 — 「最快 / 現成」這兩個詞通常標記下游 / subset 位置。

訊號 2：跨層的成本看起來高、但本層解看起來夠

「為了一個 filter 改 build pipeline 太誇張了吧」「直接前端 filter 不就好了」 — 這個內心 OS 在錯估、因為下游解的 silent 風險不在當下顯露。

訊號 3：寫完手動測一次就過

第 1 次 happy path 過了、覺得對。但 happy path 過 = 子集裡有命中、不證明 stream 全集對齊。同 #42 2 次門檻：第 1 次成功是低資訊量訊號。

訊號 4：「先這樣、晚點補資料層」

這個想法本身就是「我知道這寫法不對齊意圖、但便利度太高」 — 補不回來、會 ship 進 production silent 失敗。同 #56 視覺完成 ≠ 功能完成。

不該套用本原則的情境

「便利度跟意圖對齊反相關」這條原則在絕大多數開發情境成立、但有合理例外：

這四類共同特徵：「未來便利」這個變數的權重 ≈ 0 — 因為沒有未來（不會被讀、不會被改、不會被擴）。本原則的反相關建立在「未來便利有權重」上、權重 0 時自然不適用。

判讀：寫之前自問「這代碼三個月後會不會有人讀」 — 否 → 本原則可放寬；是 → 本原則嚴格適用。

跟其他抽象層原則的關係

本卡是這幾條的共同上位原則 — 它們都是「便利 vs 正確性的取捨」在不同情境的具體展現。

判讀徵兆

核心原則：寫程式當下的便利度跟正確性反相關、是因為兩者用的資訊狀態相反。識別「我現在在容易的位置」 = 識別「我可能在錯的層」。便利度本身是個診斷訊號、不是好東西。

延伸到測試驗證：跳過 RED 階段（不切 branch / 不重 build / 不在 buggy code 上跑測試）是便利、走 RED-GREEN 是對齊。詳見 #69 Test-First：先看到 RED 才相信 GREEN。

Self-case：本系統建立過程的便利驅動失敗

修 #55 search bug 時、跳過了 #68 Checkpoint 1（列使用者意圖完整集合）— 因為 Checkpoint 1 沒便利路徑（要刻意停下 5 分鐘想），直接從 bug 描述進策略選擇。完工後 retrospective 才發現漏了 3 個 silent 缺口（URL state / tab order / filter UI hint）。

對應本卡：「沒寫 Checkpoint 1 list 是當下便利、補完整意圖才是對齊」。我修了便利版（直接修 bug）、漏掉的 3 個案例之後才被 retrospective 抓到、又花一輪迭代回頭做。便利驅動的代價、就是事後要做兩次。

「#67 Refactor 是個謊言」延伸版：「之後做 Checkpoint 1」也是個謊言 — 動手之後 context 已經跑完、回頭重列意圖完整集成本反而高。要嘛當下做、要嘛接受漏案例。

更上位的解釋見 #72 高 ROI 無外部觸發的工作會被結構性跳過 — 本卡是 #72 在「寫程式當下選哪條路」面向的展現。

測試本身需要被驗證。 一個從沒看過 RED 的測試 = 未驗證的訊號、不是「會抓回歸的測試」。

驗證一個測試真的有用、需要看到兩個訊號：

1. RED：測試在「該失敗的版本」上失敗（buggy code → 紅）
2. GREEN：測試在「該通過的版本」上通過（fixed code → 綠）

只看過 GREEN = 不知道測試有沒有 catch 能力；只看過 RED = 不知道修復有沒有真的解問題。兩個都看到 = 測試 + 修復都被驗證。

跳過 RED 把驗收標準降到「測試跑得通」、漏掉「測試自己有沒有 bug」這層。

為什麼測試需要被驗證

測試是程式 about 程式、會有 bug

測試本身是程式碼、跟其他程式碼一樣會有 bug：

這五種都會讓「跑測試一次就 GREEN」是個假訊號 — 測試 pass 不代表測試 catch 到該 catch 的東西。

RED 是測試的「使用者驗收」

對使用者代碼、我們會用「驗收訊號」（功能跑得對）證明它有用。測試也需要驗收訊號。

「測試 catch 到 bug」這個能力的驗收訊號 = 「在有 bug 的代碼上失敗」。沒看過這個訊號就相信測試 = 跳過驗收。

對應 #42 2 次門檻：一次 GREEN 是低資訊量訊號、RED → GREEN 是 2 次跑（一次 fail 一次 pass）的高資訊量訊號。

多面向：四種情境的 RED-GREEN 應用

情境 1：修 bug

11. 先寫一個 test 重現 bug 為失敗 — 例：「filter 後 0 筆但 source 還有未載入時、應該顯示 explicit empty 而非 silent」
22. 跑測試 → RED（證明測試抓到 bug、bug 真的存在）
33. 修 code
44. 跑測試 → GREEN（證明修對了 + 測試會抓回歸）

跳過第 2 步 = 不知道測試會不會抓到、不知道 bug 真的有沒有。

情境 2：加 feature

11. 寫 acceptance test 描述新 feature 該有的行為
22. 跑測試 → RED（feature 還沒實作、應該 fail；如果 GREEN 就表示 feature 已經存在或測試太寬）
33. 實作 feature
44. 跑測試 → GREEN

加 feature 時跳過 RED 風險：feature 被誤以為實作但實際是 stub、或測試根本沒驗到 feature。

情境 3：Refactor

11. 確認當前測試 GREEN（baseline）
22. Refactor（不改 behavior）
33. 跑測試 → 仍 GREEN

Refactor 不需要 RED — 因為 behavior 沒變。如果 refactor 後變 RED、表示 refactor 改到了 behavior（變成隱性 bug）、要回頭看。

情境 4：偵錯（不確定 bug 是什麼）

11. 寫一個 test 嘗試重現問題
22. 跑測試 → 看是 RED 還是 GREEN：
3   - RED → 重現成功、現在可以著手修
4   - GREEN → 沒重現到 / 測試寫錯 / bug 在別處 → 重新理解 bug
53. 修
64. 跑測試 → GREEN

「看是 RED 還是 GREEN」這個動作本身是 debug 訊號 — 比單純猜根因有用。

「只看 GREEN 不看 RED」是反模式

反模式 1：修完才補測試（Test-after）

11. 修 bug code
22. 寫測試
33. 跑測試 → GREEN
44. ship

問題：測試從沒跑過 buggy code、不知道它能不能抓到 bug。未來 regression 進來、測試可能仍然 GREEN（測試本身有 bug）。

反模式 2：「快速跑一下測試」沒看訊號

11. 寫測試
22. 跑「應該 pass 吧」、不仔細看輸出
33. 看到 PASS → 安心

問題：可能測試 skip 了、可能測試 zero assertions、可能環境錯了。需要看「具體 catch 到什麼」、不只是「是否 PASS」。

反模式 3：測試 PASS 但 coverage 是 0

11. 寫測試 file
22. CI 跑、看到「all green」
33. 沒看 coverage report

問題：測試文件存在但實際沒 import / 沒執行、CI 報告 GREEN 是因為「沒 fail」不是「有 catch」。

不該套用本原則的情境

「先看 RED 再看 GREEN」原則在大多數情境成立、但有合理例外：

四類共同特徵：沒有「行為差異」可被測試 catch — 本原則建立在「測試該 catch 的事」上、沒事可 catch 時自然不適用。

跟其他抽象層原則的關係

本卡是把「測試這個動作本身」放進驗收體系：寫測試是動作、跑測試的訊號才是驗收。動作完成 ≠ 驗收完成。

對應的實作篇

把測試固化的實作 case 都該套用本卡：

• #11 playwright-early-in-loop — 第 2 次推理失敗切 playwright；切過去後寫的 evaluate query 跑 RED-GREEN 才驗證
• #15 layout-tests-with-playwright — 版型 debug 兩次以上寫測試固化；測試該先在「未修版型」跑 RED 才相信
• #23 verification-method-timing — 驗證方法選對之後、實際驗證需要 RED-GREEN

Retrospective 補驗證的協議

如果已經修完才寫測試（test-after）、可以 retrospectively 補 RED-GREEN 驗證：

 1# 1. Stash 現有變動 / 切到修前 commit
 2git stash
 3git checkout <pre-fix-commit>
 4
 5# 2. Cherry-pick 測試 commit（或手動複製 test files）
 6git cherry-pick <test-commit>
 7# 或：cp ../tests/foo.spec.ts tests/  # 複製測試檔過來
 8
 9# 3. Build + 跑測試
10make site && npm test
11# 預期：RED（測試抓到 bug）
12
13# 4. 切回 main / 修後版本
14git checkout main
15git stash pop
16
17# 5. 跑測試
18npm test
19# 預期：GREEN

兩次跑 + 兩個訊號（RED + GREEN）都對、測試才被驗證。Retrospective 補驗證 ≠ 不能補 — 比完全跳過 RED 好、比 test-first 弱。

協議已 codify 為 make verify-red-green PRE_FIX=<commit-sha>（見 Makefile）— 五步驟自動化、不需要每次手動 stash / checkout / build / restore。

Self-case：本卡誕生過程的 dogfooding 失敗

本卡是從一次真實的 dogfooding 失敗抽出來的。修 #55 Filter × Source 層錯位 bug 時、流程是：

1. 修 code（multi-index 策略）
2. 寫 4 個 Playwright tests
3. 跑測試 → 4/4 GREEN
4. 看起來完工

User 問「修改之前有先寫測試確保符合預測狀態嗎」— 才意識到沒走 RED。Retrospective 補驗證後發現：4 個測試只有 1 個真的 catch 到 bug、其他 3 個對 buggy code 也 PASS（placebo 測試）。

強化後（用 network-level + structural assertion 替換弱 invariant）：buggy code 上 1/4 PASS、3/4 FAIL。Fixed code 上 4/4 PASS。RED-GREEN 兩個訊號都看到、測試才真的驗證。

如果不做 retrospective、會帶著 3/4 placebo 測試 ship — 表面 4/4 GREEN、實際只有 1 個真的防回歸。「跑得通」≠「會 catch」這個區別、只有走過 RED 才知道。

跳過 RED 是 #72 高 ROI 無外部觸發的工作 在測試協議的展現 — 修法不是「下次記得」（L1 紀律會失敗）、是 make verify-red-green PRE_FIX=<sha>（L3 工具觸發）+ pre-commit hook 提醒（L3 結構觸發）。

判讀徵兆

核心原則：測試不是「跑得通就有用」、是「跑出該有的訊號才有用」。RED 是測試的驗收訊號、跳過 = 接受測試本身可能是壞的。RED → GREEN 兩次跑、才證明「測試真的會 catch + 修復真的解掉 bug」。

State 的儲存層決定它的特性 — 可分享 / 可恢復 / 可導航 的 state 該寫進 URL、不寫進 = silent 把這些特性犧牲掉。

寫 stateful UI 時、每個 state 的儲存位置是個設計選擇 — 不選 = 預設用 in-memory = 預設犧牲所有上面五個特性。

為什麼 URL 容易被忽略

URL 是隱形維度

In-memory state 在 React useState / Vue ref / vanilla 變數裡 — 寫起來最便利、是「預設位置」。URL state 需要 URLSearchParams + history.pushState + popstate listener、寫起來成本高。

#67 寫作便利度跟意圖對齊反相關 直接解釋為什麼：URL state 是「對齊使用者期望」的位置（使用者預期 URL 包含 state、能分享）、in-memory 是「便利位置」。預設便利、要刻意才走對齊。

沒寫 URL state 的失敗訊號是 silent

使用者打開搜尋頁、輸入「pagefind」、選擇 title-only filter、看到結果。這時：

• 複製 URL 分享給朋友 → 朋友打開看到空白搜尋框（query 不在 URL）
• 重整頁面 → 自己也看到空白搜尋框
• 點 back → browser back 跳離搜尋頁、不是回到「沒 filter 的同個搜尋」

這三個動作沒有 error、沒有崩潰、就是「state 不見了」。使用者通常以為「網站就這樣」、不會 report bug。Silent 失敗 = 維護者永遠不知道有問題。

對照 #55 Filter × Source 層錯位 — 都是 silent 失敗、都是「該存在的東西不在」。

State 該寫進 URL 的判準

三問

1. 使用者會分享這個 state 嗎？— 是 → URL（複製連結即帶 state）
2. 使用者 reload 後預期 state 還在嗎？— 是 → URL 或 sessionStorage
3. 使用者期望 browser back/forward 在 state 之間導航嗎？— 是 → URL

任一個「是」 → URL。

反向判準：什麼不該寫進 URL

多面向：常見 UI 元素的 URL state 對照

面向 1：Search filter（這次任務的 case）

1Query string、scope filter、type filter、tag filter
2→ 都該進 URL：使用者會分享「我搜什麼 + 怎麼篩」

範例 URL：/search/?q=pagefind&scope=title&type=post&tag=js

面向 2：Tab / step navigation

1Active tab、wizard step
2→ 該進 URL：分享 = 直接打開該 tab/step

範例：/settings/?tab=notifications、/checkout/?step=payment

面向 3：Sort / pagination

1排序欄位、頁碼
2→ 該進 URL：分享 = 朋友看到同樣排序的同一頁

範例：/posts/?sort=date_desc&page=3

面向 4：Modal / drawer 開合

1看情境：
2- 重要 modal（圖片預覽、編輯對話框）→ URL（可分享 / back 關閉）
3- 純 UX 提示 modal（welcome tour）→ in-memory（不該分享）

面向 5：Theme / UI preference

1Dark mode、字型大小
2→ localStorage（跨 session 但不分享、跟 device 綁）
3不進 URL（不會「分享你的 dark mode 設定」）

URL state 的實作模式

讀：載入時從 URL 同步到 component state

 1function getInitialState() {
 2  const params = new URLSearchParams(location.search);
 3  return {
 4    query: params.get('q') || '',
 5    scope: params.get('scope') || 'all',
 6    type: params.get('type') || null,
 7  };
 8}
 9
10const initialState = getInitialState();
11// component 用 initialState 初始化

寫：state 變動時同步到 URL

 1function syncUrl(state) {
 2  const params = new URLSearchParams();
 3  if (state.query) params.set('q', state.query);
 4  if (state.scope && state.scope !== 'all') params.set('scope', state.scope);
 5  if (state.type) params.set('type', state.type);
 6  const url = `${location.pathname}${params.toString() ? '?' + params.toString() : ''}`;
 7  history.replaceState(null, '', url);
 8}
 9
10// 每次 state 變動觸發
11onStateChange((newState) => syncUrl(newState));

選擇 replaceState vs pushState：

• replaceState：每次 state 變動覆蓋當前 history entry — back/forward 跳過中間狀態
• pushState：每次 state 變動加新 history entry — back 回到上一個 state

通常 search filter / sort / pagination 用 replaceState（typing 太快、不該每個字符一個 history entry）；tab / step 用 pushState（每個 step 該 back 回上一個）。

雙向：聽 popstate 處理 back/forward

1window.addEventListener('popstate', () => {
2  const state = getInitialState();
3  applyStateToUI(state);  // back/forward 後、把 state 套回 UI
4});

沒 listen popstate = back/forward 不會觸發 UI 更新、URL 跟 UI 不同步。

不該套用本原則的情境

「URL 是 state 儲存層」原則在「公開可分享的 UI」成立、但有合理例外：

跟其他抽象層原則的關係

對應的實作篇

• 搜尋頁的 scope filter URL persistence — Phase 1+2 修完後 retrospective Checkpoint 1 才發現遺漏（#68 dogfooding）
• 任何 search / list / dashboard UI — 都該檢視 URL state coverage

判讀徵兆

核心原則：URL 是 stateful UI 的隱形儲存層。沒寫 URL state = silent 犧牲分享 / 恢復 / 導航三個 UX 特性。寫之前跑三問（分享？reload？back/forward？）、任一個是 → URL。

Tab 順序 = DOM 順序 = 使用者 mental model 的互動順序、三者該對齊。

三者偏差的後果：

• DOM ≠ mental model：視覺 / tab 順序跟使用者期望不一致、a11y 體驗差
• DOM ≠ tab order（用 tabindex > 0）：DOM 改變時 tab 順序維護成本爆炸（#52 反模式）
• 全對齊：DOM 簡單、tab 自然、a11y 預設正確

要解決不對齊、優先重排 DOM、不要用 tabindex 強制覆寫。

為什麼三者該對齊到 DOM 順序

Tab 順序跟 DOM 順序綁定是 spec 規定

HTML5 spec：tabbable elements 預設依 source order（DOM 順序）navigate。要改變只能用 tabindex 覆寫。

tabindex 三種值：

tabindex > 0 反模式（同 #52 鍵盤可達性）：

• 全頁面只要有任何元素用 tabindex > 0、整個 tab 順序變混亂（其他 0 / 不寫的元素都被推到後面）
• 維護成本：DOM 改了、所有 tabindex > 0 的數值都要重排
• A11y：screen reader 跟視覺使用者體驗到不同順序

唯一合法用法：要把元素「移出 tab cycle」用 tabindex="-1"（例如 modal 開啟時鎖住背景）。

Mental model 順序由 UI 設計決定

互動式 UI 隱含一個流程：使用者預期「先做 X 再做 Y」。例如：

設計者腦中有這個順序、寫 HTML 時要把它具體化成 DOM 順序。DOM 順序就是把 mental model 寫進 code 的方式。

多面向：常見不對齊 case

面向 1：Filter 在 search input 之前（這次任務的 case）

1<!-- DOM 順序：scope 先 → search input 後 -->
2<div class="search-scope">...</div>
3<div id="search"></div>  <!-- pagefind input 在裡面 -->

Tab 順序：scope radios → search input。但 mental model 是「先打字再篩選」、Tab 應該先到 input。

修法：DOM 重排、把 scope 移到 #search 之後。視覺位置由 CSS position: absolute 控制、不受 DOM 順序影響。

面向 2：Submit 按鈕在 form 中間

1<form>
2  <input name="email">
3  <button type="submit">送出</button>  <!-- 太早 -->
4  <textarea name="message"></textarea>
5</form>

Tab 順序：email → submit → textarea。使用者打完 email 按 Enter 就送出、textarea 還沒填。

修法：submit 移到所有 input 之後。

面向 3：Logo / nav 在主要 CTA 之前

1<header>
2  <a href="/">Logo</a>
3  <nav>... 5 個 links ...</nav>
4</header>
5<main>
6  <button>主要 CTA</button>  <!-- 使用者要按這個 -->
7</main>

Tab 順序：6 個 nav links → CTA。使用者要 tab 6 次才到 CTA。

修法：考慮加 「skip to main content」link（A11y 標準做法）— <a href="#main-content" class="skip-link">。第一個 tab 就跳過 nav 到 main。

面向 4：Modal 開啟時 background 仍 tabbable

1<div class="background-content">
2  <a href="...">某連結</a>  <!-- 仍可 tab 到 -->
3</div>
4<div role="dialog">
5  <input>
6  <button>確認</button>
7</div>

Tab 順序：背景連結 → modal input → confirm。使用者 tab 出 modal 跑回背景。

修法：modal 開啟時、用 inert attribute（modern）或所有背景元素設 tabindex="-1"（傳統）把它們踢出 cycle。<dialog> native 自動處理。

不對齊的修法：優先重排 DOM

第一順位：重排 DOM

把元素照 mental model 順序排在 HTML / template 裡。視覺位置如果跟 DOM 順序不同、用 CSS order（flex / grid）、position: absolute、grid-template-areas 控制。

1<!-- DOM 順序對齊 mental model：input → scope → drawer -->
2<div id="search"></div>
3<div class="search-scope">...</div>

1/* 視覺：scope 浮在 input 跟 drawer 之間（跟 DOM 順序無關） */
2.search-shell { position: relative; }
3.search-scope {
4  position: absolute;
5  top: calc(var(--input-h) + 8px);
6}

Tab 順序自然對齊 DOM、視覺位置由 CSS 獨立控制 — 兩個維度解耦、不互相影響。

第二順位：JS 動態移動 DOM

如果元素因為 framework 限制無法 hard-coded 在對的位置（例如某 vendor library 強制 mount 點）、用 JS 在 mount 後 reparent 元素到對的位置。

1// PagefindUI mount 後、把 scope 移到 input 跟 drawer 之間（如果 framework 允許）
2const scope = document.querySelector('.search-scope');
3const drawer = document.querySelector('.pagefind-ui__drawer');
4drawer.parentElement.insertBefore(scope, drawer);

風險：framework 重渲染可能 reparent 回去（#5 framework-managed DOM）。要驗證穩定性。

第三順位（不推薦）：tabindex 強制

1<input tabindex="1" name="search">  <!-- 反模式：tabindex > 0 -->
2<div tabindex="2" class="search-scope">...</div>

只在前兩種都做不到時用。維護成本高、a11y 跟設計工具支援差。

不該套用本原則的情境

「DOM = tab = mental model 三者對齊」原則在多數情境成立、但有合理例外：

四類共同特徵：沒有清楚的「使用者該先做 X 再做 Y」流程 — 本原則建立在「有 mental model 可對齊」上、沒有時自然不適用。

跟其他抽象層原則的關係

對應的實作篇

• 搜尋頁 scope filter 在 search input 之前的 tab 順序問題 — Checkpoint 1 retrospective 找到（#68 dogfooding）
• 任何「先選範圍再操作」vs「先操作再選範圍」的 UI 設計 — 都該檢視 tab order 是否對齊

判讀徵兆

核心原則：DOM 順序是寫進 code 的 mental model、tab 順序是使用者體驗的 mental model — 兩者該由「重排 DOM」對齊、不該由「tabindex」強制。視覺位置跟 DOM 順序解耦（用 CSS 控制）、讓兩者各自獨立優化。

工作有兩個獨立維度：ROI 高低 × 是否有外部觸發。

「高 ROI + 沒外部觸發」是個結構性陷阱 — 知道該做、做了有大回報、但永遠不做。靠「我下次記得」不可行。修法是結構性對策：把外部觸發補上。

為什麼靠紀律不可行

「之後做」是個謊言（共同結構）

#67 我等下會 refactor 是個謊言 已經點到一個面向。把它推廣：

「之後做 X」這個 plan 在 X 屬於「高 ROI + 無觸發」時、預期完成率接近 0。不是個人意志問題、是結構問題：

往下走、外部觸發越弱、執行率越低。最弱的「下次有空我做」≈ 0% — 因為「下次」永遠是「現在」、「現在」永遠有更急的事。

為什麼結構性、不是動機問題

「沒外部觸發」 = 沒人催、沒 deadline、沒 alarm、沒 PR review 提醒。腦中有 working memory 限制、優先處理「正在叫」的事。「叫」這個動作只有外部能做 — 自己對自己叫沒用（因為「自己叫自己時」跟「自己接受自己叫時」是同個 context）。

這跟意志力、自律、責任感無關 — 即使最自律的人、面對「沒人催的高 ROI 工作」，執行率也大幅下降。靠紀律 = 預期失敗、然後責怪自己。

多面向：高 ROI + 無觸發的工作清單

每一條都對應某張既有卡的具體展現：

寫程式類

• Refactor（沒功能壓力） — #67
• Test-first 的 RED 階段（修完才補測試） — #69
• Checkpoint 1（列使用者意圖完整集） — #68
• Ship 前 E2E case 設計 — #68
• Code review feedback 的 follow-up（reviewer 留 comment、作者回「之後改」）

維護類

• Migration cleanup（feature flag 拔除、舊 path 砍掉）
• Deprecated 程式碼移除
• Dependency upgrade（沒 breaking 但該升）
• Performance regression 修復（測量上有但使用者沒抱怨）

文件類

• API doc / README 更新
• 事後檢討卡片寫入（這個 cards-skills 系統就是 case — 沒 user 提醒就不會做）
• Decision log / ADR

監控類

• Setup observability / log monitor（#68 Checkpoint 4）
• Alert 規則 review
• Dashboard 維護

知識類

• Onboarding doc 更新
• Post-mortem 寫完發出去
• 跨團隊 share session

共通結構：每一項都「知道該做、做了有大回報、沒人催就不做」。即使是寫過卡片教自己原則的人（meta-level dogfooding 失敗）也一樣會跳過。

修法：結構性對策的五個層級

從弱到強：

L1：個人紀律（最弱、不可行）

「我下次記得」「我會自律」 — 已經證明 ≈ 0% 執行率。不該寫進 plan。

L2：自我排程（弱）

「每週五下午 refactor 1 小時」「每個月初 review TODO」。比 L1 強、但仍依賴自己當下不分心、不被「更急」的事拉走。執行率約 30-50%。

L3：外部工具觸發（中-強）

把觸發外化到工具：

• CI / pre-commit hook：commit test file 自動提醒「跑過 RED 嗎」
• Scheduled scripts：cron job 跑 lint / dep audit / migration cleanup detector
• Calendar event：固定時間、有 alarm
• PR template：強制填「Checkpoint 1 列了哪些 case」

工具不會忘、不會拖、不會選擇性執行。執行率 80-95%。

L4：團隊流程（強）

把觸發外化到別人：

• Pair programming：另一個人在旁邊、會問「為什麼跳過 X」
• Code review block：reviewer 不通過 PR 直到 X 完成
• Standup commitment：公開講出「我這週要修 X」、隔天會被問
• Retro action items：團隊紀錄 + 追蹤、不個人擁有

執行率 90-99%。

L5：結構性不可能（最強）

讓不做 X 變成 ship 不出去：

• Tests required：CI fail 不能 merge
• Build fails on stale doc：lint 規則檢查 doc 跟 code 同步
• Feature flag 自動 expire：超過某時間、flag 被自動移除
• Linter 禁用 deprecated API：用了就 build 錯

100% 執行率（系統強制）。代價：建立成本高、要團隊認可。

選擇法則：先看哪個層級剛好夠、不要用 L5 解 L3 能解的問題（過度工程）、也不要用 L1 解 L4 才能解的問題（會失敗）。

「想到就動手」是次優、不是最優

直覺反應是「想到該做就立刻做」、避免拖延。這在「想到時剛好沒手邊事」可行、但實際多半「想到時手邊有事」 — 變成中斷當前工作、context switch 高昂。

更穩定的策略：把想到的東西塞進已存在的觸發機制：

• 想到「這個重複了該抽 helper」 → 開 issue / TODO 給下次 refactor session
• 想到「這個 case 沒測」 → 加進 PR template 的 Checkpoint 1 list
• 想到「這個 doc 過時了」 → 打開 doc 在 commit 寫 // TODO: 更新 X

「動手」的時機由觸發決定、不由「想到」決定。想到 = 觸發機制的 input、不是執行的 trigger。

不該套用本原則的情境

「高 ROI + 無觸發 = 結構性跳過」原則在多數情境成立、但有合理例外：

四類共同特徵：「外部觸發」這個變數已經有解或不存在 — 本原則建立在「沒觸發 = 跳過」上、有觸發或不需要時自然不適用。

跟其他抽象層原則的關係

本卡是 meta-#67/#68/#69 — 把「為什麼這些動作會被跳過」抽出來、答案是「沒外部觸發 + 靠紀律失敗 = 結構性跳過」。三張卡的修法都是「補外部觸發」、不是「自己更努力」。

對應的實作篇 / 系統建設

把本原則套用到本系統的具體 case：

• make verify-red-green script（#69）— L3 工具觸發、把 retrospective 流程從文字協議升級成可執行 target
• playwright CI workflow（push / PR 觸發）— L5 結構性、test 不過就無法 merge
• md-check workflow — L5 強制、卡片格式不對 build fail
• 本卡誕生過程 — User 提問是 L4 外部觸發、把「該回頭抽 meta」變成有壓力的動作（不然不會做）

每一個都是「把高 ROI + 無觸發的工作、補上對應層級的觸發」。

判讀徵兆

核心原則：高 ROI 但無外部觸發的工作 = 結構性跳過、不是個人問題。修法是把觸發外化（工具 / 流程 / 結構）、不是「我下次記得」。「之後我會 X」是 plan-level 警訊、應該轉成「X 會被 Y 觸發」的具體機制。

多策略選擇（如 #59 五策略、#73 五匹配模式）預設不是單選。能疊加的策略應該疊加、互斥的才需要選。

最常見的疊加：root-cause 結構性修法 + 使用者感知補強（例如 multi-index 解層錯位 + UX hint 解 prefix-match 預期落差）— 解不同層、互不干擾、合在一起的覆蓋面 > 單選任一。

為什麼預設單選是錯誤前提

呈現多選項時容易進「適配性比較表 → 選最高分」的單選思維。這個思維對「互斥工具選擇」（Vue / React、Postgres / MySQL）成立、對「補強型策略」不成立：

• 結構性修法（修正根因、長期穩）— 通常需要時間 + 風險
• UX 補強（解使用者感知、立即可見）— 通常 ROI 立刻、但不解根因

兩者解的問題層不同：根因解了、使用者立刻感受到的混亂仍在；UX 蓋過去了、根因仍在累積技術債。預設單選 = 強迫使用者在「立即解使用者痛苦」與「長期解結構問題」之間二選一、其實兩個都該做。

疊加可行的三條判準

某兩個策略 X + Y 可疊加 ⇔ 滿足以下全部：

1. 解不同層

X 動結構 / 資料 / 演算法、Y 動 UI / 訊息 / 預期管理。同層的兩個策略通常衝突（兩種 cache 策略、兩種 routing 策略），不同層的多半互補。

判讀：把問題分成「根因 / 訊號 / 補償」三層、每層挑 1 個策略 = 疊加組合。

2. 沒副作用衝突

X 加上 Y 不會放大彼此副作用、不會產生新 bug。例：multi-index（佔 build time）+ UX hint（佔畫面空間）— 兩個 cost 維度不同、不互相放大。

反例：fetch-until-quota（多次 round trip）+ aggressive prefetch（更多 round trip）— 同維度副作用會疊加、可能爆炸。

3. 增量成本 ≤ 預算

第二個策略的實作 + 維護成本 ≤ 它解的問題價值。如果 X 已經解掉 80% 問題、Y 解剩下 20% 但成本是 X 的兩倍 → Y 就是過度工程、不該疊加。

典型疊加模式

模式一：Structural fix + UX patch

Structural 解根因、UX 解使用者當下混亂。即使 structural 還沒 ship、UX patch 可以先 ship 解眼前問題。

模式二：Defensive + Optimistic

Defensive 處理失敗、Optimistic 處理成功 — 兩個 happy path 共存、不衝突。

模式三：Now + Later

「先 ship X 解眼前、Y 下輪做」是一種隱式疊加 — 不是放棄 Y、是延後到風險更可承受的 release window。判準見 #76 分批 ship。

模式四：Selector strategy 疊加（#46-#50）

#46 / #47 / #48 / #49 四張 selector 起點 pattern 卡乍看互斥（每個元件只能選一個起點）、實際在同一個 handler 內可疊加：

同一份 component code 可同時用 #46 + #49（外部 portal 用 document、內部用 closest）— 解不同 selector context、不衝突、增量成本低 = 滿足三條判準。

判讀：「這幾個 pattern 是同層次（互斥）還是不同 context（互補）？」不同 context = 疊加。

反模式：強迫單選的代價

何時該堅持單選

四類共通：疊加的代價 > 疊加的收益。其他情境都該先檢查「能不能疊加」。

跟其他卡的關係

判讀徵兆

核心：策略選擇問「能不能疊加」優先於「選哪個」 — 多數工程問題的最佳解是「多層次組合」、不是「找出唯一答案」。

寫到「該 ship 哪些」時、預設分批：把 changes 沿三軸切 — 使用者可見性高 + 風險低 + 驗證簡單 的先 ship、結構性 + 風險高 + 需驗證 的下輪。對抗「都做完才能 ship」的整體性衝動。

分批的真正價值：降低每次 review 的 cognitive load + 加速使用者拿到價值 + 讓回退單位更小。整批 ship 的代價是 review 變慢、bug 排查面變大、出問題回退要拖整批。

三軸切分

切「現在 ship vs 下輪 ship」用三個維度：

軸 1：使用者可見性

• 高：使用者立刻能感受到差異（UI 改變、訊息精準、互動更順）
• 低：純內部結構（refactor、index 重建、protocol 升級）

可見性高 → 早 ship 拿價值；可見性低 → 早晚 ship 差別不大、可以等更多 confidence。

軸 2：風險暴露面

• 低：純加法（新檔案、新欄位、新 endpoint）— 不影響既有 path
• 中：修改既有 code path 但有 fallback / 開關
• 高：替換、刪除、結構重組 — 沒退路或退路成本高

低風險 → 早 ship、出問題範圍小；高風險 → 等 confidence、配 staged rollout / feature flag。

軸 3：驗證需求

• 低：邏輯簡單、unit test 夠、可肉眼驗收
• 中：需要 E2E、多瀏覽器 / 多裝置驗證
• 高：需要長時觀測、production 流量壓測、A/B 比較

低驗證需求 → 早 ship；高驗證需求 → 等驗證流程跑完、不為趕時間跳過驗收。

切分矩陣

關鍵 row：「高可見 + 低風險 + 低驗證」就是先 ship 的甜蜜點 — 例：UX hint、empty state 訊息、明顯的 UI 修正。

「先 ship D、B/C 下輪」的典型範例

來源：#73 prefix-match 限制

D 滿足「高可見 + 低風險 + 低驗證」、立刻 ship 解眼前混亂。B/C 解根因、但風險與驗證需求高、下輪做。這個排序不是「重要程度」、是「ship 順序」 — 重要程度 B/C > D、但 ship 順序 D > B > C。

為什麼「全做完才 ship」是反模式

幾個常見藉口 + 為什麼站不住：

實際上「全做完才 ship」最常見的真實原因是：沒花時間想分批。預設分批就會自然分。

分批反模式

何時該堅持「一次完整 ship」

四類共通：ship 一半比都不 ship 更壞。其他情境分批優先。

跟其他卡的關係

判讀徵兆

核心：「ship 順序 ≠ 重要程度」。使用者可見性高 + 風險低 + 驗證需求低 = 先 ship 甜蜜點、即使在重要程度上不是 top。等所有結構性修法都做完才 ship、是把重要程度誤當成 ship 順序的常見錯誤。

對話中要使用者決策時、有五個獨立維度可以選擇 — 不該預設 collapse 到單一格子：

核心命題：每個維度都是獨立的、五個維度展開後是 2^5 = 32 種組合。預設都選窄格 = 對使用者問最窄的問題、結果通常品質低。應該針對每個情境 reason about「這維度該選哪邊」、不是無腦套預設。

為什麼預設都是窄格

每個維度的窄格都是「最容易寫」的選項：

• 開放問比結構表少打字
• 單策略比「策略 A + 補強 B」少思考
• 一次做完比設計分批邊界少規劃
• 立刻決比寫延後條件少協議
• 單選 radio 比寫「互不衝突、可全選」少說明

合起來：窄格是 #67 寫作便利度 的具體展現 — 每一維都是「容易寫但跟使用者意圖反相關」的方向。

預設窄格的真正代價：使用者被迫在錯位的問題空間中作答、即使最終做了決定、決定的品質受呈現格式 cap。

五維度的判讀次序

實務上、依序檢查五個維度：

步驟 1：選項類型（#78）— 是執行還是反省？

執行類決策（用 A 還是 B 工具、選哪個策略） → 通常單選。 反省類決策（這次學到什麼、下一步該往哪走） → 通常複選。

判讀：「這次 output 該收斂到一個答案還是攤開多面向？」收斂 → 單選；攤開 → 複選。

步驟 2：時間軸（#77）— 現在能決嗎？

context 完整 → 現在決。 context 缺 → 延後 + 寫條件。

判讀：「我（agent）有沒有提供能讓使用者下決定的全部資訊？」沒有 → 主動標延後選項。

步驟 3：策略數（#75）— 單選還是疊加？

策略間互斥（同 slot 只能放一個） → 單選。 策略間互補（解不同層） → 疊加。

判讀：「這些策略是否解不同層？」是 → 提疊加組合（如 structural + UX）。

步驟 4：批次邊界（#76）— 一次還是分批？

純 atomic（拆了不能用） → 一次。 可分（高可見 + 低風險的部分能獨立 ship） → 分批。

判讀：「先 ship 高 ROI / 低風險那部分、剩下下輪」是否可行？可行 → 分批。

步驟 5：呈現格式（#74）— 開放還是結構？

純探索 / 主觀偏好 → 開放。 有客觀適配性可比 → 結構表 + 推薦。

判讀：「我能不能列選項 + 適配性 + 推薦？」能 → 結構；不能 → 探索性開放。

反模式：collapse 到單一格子的常見變種

每個變種都是「五個維度都選窄格」的具體展現。

鬆綁後的範本

把五維選擇全部明示的決策呈現：

 1## 我看到的選項
 2
 3| 選項 | 適配性 | 取捨 |
 4|---|---|---|
 5| A 結構性修法 | 解根因 | 風險高、要驗證 |
 6| B UX 補強 | 立即可見 | 不解根因 |
 7| C 不做 | 0 成本 | 使用者繼續手動 |
 8| **延後（補 X 再決）** | 等 context | 條件：跑完 telemetry |
 9
10## 推薦組合
11
12**B 先 ship、A 下輪**（疊加 + 分批）— B 解眼前痛、A 在 telemetry 證實後再投入結構修法。C 不選因為使用者會抱怨。
13
14## 你的選擇空間
15
16- 同意（B 現在、A 下輪）
17- 改順序（A 先、B 下輪）
18- 加 / 減：把 C 加進來、或把 B 拿掉
19- 延後：先補 telemetry 再決
20- **任意組合可複選**（除非說明互斥）

關鍵：主動展開五個維度的選擇空間、不要預設 collapse。使用者要選窄格是他們的選擇、不是你預設替他們選。

跟其他抽象層原則的關係

子卡片地圖

#74-#78 各自對應一個維度、互不重疊、合起來覆蓋 32 種決策對話組合。讀法建議：

• 遇到具體情境：依步驟 1-5 找對應卡（例如「這個是反省題嗎？」→ #78）
• 第一次接觸：先讀本卡（#79）建立五維 mental model、再讀子卡學模板
• review 自己對話：拿五維 checklist 掃一遍、看哪維 collapse 了

判讀徵兆

核心：對話中的「決策」是多維選擇空間、不是單點題目。預設展開、選窄格要證明 — 跟 #78「不互斥是預設、互斥要證明」同一條結構。把選擇空間攤開的成本是「多打幾段字」、不攤開的代價是「使用者長期被塞進錯位的格子」。

知識卡片系統的成型不是「想清楚再寫」、是多輪迭代浮現：

1原始對話素材
2   ↓ 識別重複結構
3原子卡（每張一個小現象）
4   ↓ 串連、識別共同骨架
5meta-卡（抽上層原則）
6   ↓ 沉澱成可重複使用的 protocol
7reference（可直接套用的 checklist + 模板）
8   ↓ L3 觸發機制
9SKILL（自動觸發 reference）

每層都解上一層的限制、不是替代。原子卡保留具體 case 的細節（被反例反駁時可保留）、meta-卡提供跨情境的判讀框架（避免每次重新推理）、reference 沉澱成可直接套用的步驟（消除「知道但忘記用」的鴻溝）。

為什麼一次寫不完

第一次接觸現象時、看到的是具體 case 的表面：

• 看到「使用者說『我再想想』」 → 先寫成「[#77] 延後是合法選項」
• 看到「使用者說『1+2』」 → 先寫成「[#78] 反省題複選」
• 看到「使用者反駁推薦」 → 先寫成「[#74] 決策呈現格式」

每張原子卡解 1 個情境、自包含可讀。但串連在一起時才浮現的結構（例：「五個獨立維度」）需要看到 ≥ 3-5 張原子卡之後才看得出。第一次寫不出來、不是因為沒想清楚、是因為原料不夠。

催熟原子卡之前先寫 meta-卡 = 從少數 case 過度推論、產生 over-fit 結構、後續發現新 case 不符就要重寫。

三層的職責分工

Layer 1：原子卡

範圍：單一現象 / 單一錯誤 / 單一情境。

特徵：

• 從具體事件浮現（事後檢討）
• 自包含、不依賴其他卡也能讀
• 含「反模式 / 修法 / 何時不適用」三段
• 給未來自己看：「啊我再次遇到這個」

例：#77 「現在不決定」是合法選項 是從一次具體對話中「使用者說『不用現在決策』、agent 加壓」浮現。

Layer 2：Meta-卡

範圍：N 張原子卡的共同骨架。

特徵：

• 不是新原則、是把已存在的原則上抽
• 通常出現在「寫 N 張原子卡之後、發現他們其實同一件事」
• 提供跨情境判讀（“這個情境屬於哪一維度?"）
• 給「已有 mental model 的讀者」加深、不取代原子卡

例：#79 決策對話的五個維度 是寫完 [#74-#78] 五張原子卡後、發現他們各對應一個獨立維度。沒寫 #79 之前 #74-#78 是五張平行卡、寫完 #79 後形成有結構的網。

Layer 3：Reference

範圍：把 N 張卡的判讀流程沉澱成可直接套用的 step-by-step。

特徵：

• 不是教學、是 lookup table + checklist
• 在實作中被翻開、不是讀爽的
• 結尾有 self-check 讓使用者驗證自己沒漏
• 跟一張具體任務 / 觸發情境對應

例：references/decision-dialogue.md（在 SKILL 內）— 把 #74-#79 翻譯成「五步判讀 + 完整模板 + self-check」、agent 寫 decision 之前看一遍就夠了。

多層迭代的訊號：什麼時候該往上抽？

訊號 1：寫第 N 張卡時、發現大段內容跟前一張重複

→ 兩張卡共用某個結構、抽出 meta-卡。例：寫 [#78] 反省題複選時、引用 [#74] 推薦格式 = 暗示有上層共骨。

訊號 2：跨卡 cross-link 變密、單張卡的「跟其他卡的關係」段持續長

→ 知識網密度足夠、可抽 meta-卡作為樞紐。

訊號 3：實作中要回查多張卡才能完整 apply

→ 沉澱成 reference、減少回查成本。

訊號 4：「我之前是不是寫過類似的」第 3 次出現

→ 不是「沒寫過」、是 meta-結構模糊、無法用既有卡 frame 新情境。需要 meta-卡。

反模式：跳層的代價

觀察：多層迭代不是線性、是 spiral

實際上的迭代不是「Layer 1 全寫完才寫 Layer 2」、而是：

1寫 #74 → 寫 #75 → (浮現 meta) → 草稿 #79 →
2寫 #76 → (補 #79) → 寫 #77 → (補 #79) →
3寫 #78 → 完成 #79 → 寫 reference → SKILL 整合

每次新卡可能反過來修改 meta-卡、reference 也可能反過來指出原子卡缺角。Spiral 結構接受迭代修正、線性結構假裝一次寫對。

跟其他抽象層原則的關係

套用到本系統的具體 case

content/report/ 的 80+ 卡片成型路徑：

1. 第 1-2 輪（#1-#30）：純事後檢討、單張原子卡、互不串連
2. 第 3 輪（#31-#45）：開始抽 pattern 卡、識別重複結構
3. 第 4 輪（#42-#45 + #67-#72）：抽出第一批 meta-卡
4. 第 5 輪（#55-#73）：寫 #59 五策略時發現 meta-卡需求、回補 #67-#73
5. 第 6 輪（#74-#80）：dialogue 中浮現決策協議、寫原子卡 + meta + reference
6. 下一輪：可能會在 #80 上面浮現另一層 meta（process 反思的 meta）

每輪都不是「一次寫完」、是 spiral 中的一個 lap。

判讀徵兆

核心：知識卡片系統不是寫一次的文件、是長期 spiral 迭代的 living system。接受「第一次寫不對、會迭代」這個前提、就會在每次接觸新現象時先寫原子、累積到一定 N 後抽 meta、最後沉澱 reference。反過來的「想清楚再寫」是模仿線性開發、跟知識浮現的真實結構不對齊。

驗證手段（hook / lint / CI / review / spiral / test / production observation）有不同的「錯誤偵測粒度」、必須跟錯誤的層次對齊：

「攔截」這個動作預設已經知道錯誤的形狀（hook 寫死規則 = 已知錯誤）。真正會出錯的是「不知道形狀」的錯誤 — 那需要多輪 review / spiral 收斂、不是即時攔截。

為什麼 hook 對行為錯誤無能為力

Hook / lint / type checker 的本質是 字串匹配 / structural check — 看得到形狀、看不到意圖。所以：

• 抓得到「commit message 沒含 issue 號」 — 字面 pattern
• 抓得到「test file 沒對應 source file」 — 結構檢查
• 抓得到「YAML frontmatter 缺欄位」 — schema check
• 抓不到「這個推薦不夠明確、騎牆」 — 需要理解語意
• 抓不到「決策 collapse 到 yes/no、漏五維」 — 需要判斷意圖
• 抓不到「思考路徑跳過 RED phase」 — 需要追溯 reasoning
• 抓不到「過度疊加策略、超過必要」 — 需要 judgment

Hook 試圖用字串規則模擬語意檢查 = 規則永遠 over-fit 或 under-fit：寫太嚴 → 大量 false positive 把好的也擋掉、寫太鬆 → 行為錯誤照樣通過。

反模式：用 hook 蓋行為錯誤的代價

False confidence 比沒保護更危險

寫了 hook 之後、心理上會覺得「有保護」。實際上 hook 只擋字面、行為錯誤照常發生 — 但作者不再警覺、因為「CI 通過了應該沒事」。

對比沒 hook 的情境：作者知道沒保護、會主動多看一次。

第二行是最危險的組合 — 加 hook 卻不知道 hook 範圍、會比沒 hook 更糟。

規則膨脹：嘗試「再寫一條 hook」永遠補不完

每次行為錯誤通過、直覺反應是「再加一條 hook 規則」。但行為錯誤的形狀是無限的、規則永遠補不完。最終結果：

• 規則越來越多、越來越複雜
• 維護成本爆炸
• 仍然漏接行為錯誤
• 還產生越來越多 false positive 把好的擋掉

→ 規則膨脹是「用錯工具」的訊號、不是「規則寫得不夠細」的訊號。

多輪精煉的設計：spiral 取代攔截

行為錯誤的正確驗證手段是 multi-pass spiral：

1第 1 輪：先做、看結果
2   ↓ 發現 N 個問題
3第 2 輪：依結果調整 / 補強
4   ↓ 發現 N-k 個問題
5第 3 輪：dogfood / 實際使用 / 反向自查
6   ↓ 收斂
7（沒新問題 → 結束、有新問題 → 繼續迭代）

關鍵設計：不是「攔截錯誤」、是「設計每輪能 catch 不同層的錯誤」。

各輪的職責分工

每輪解上一輪沒看到的問題、不是重複同一檢查。

不同輪適合不同的「不對齊」

• 第 1 輪 vs 需求 → 看「做出來的跟要的對不對齊」
• 第 2 輪 vs 邊界 case → 看「漏哪些情境」
• 第 3 輪 vs 真實使用 → 看「用起來感覺對不對」
• 第 N 輪 vs 上層原則 → 看「有沒有違反某個 meta-原則」

每輪有不同的角度、新角度才能 catch 上一輪 miss 的東西。

何時 hook 真的足夠

某些情境純字面就夠、加 hook 是對的：

五類共通：錯誤形狀完全字面、且漏掉成本高 / 字面就是 evidence。其他情境 hook 都會在某個時點走到 ceiling。

識別 ceiling：什麼時候該換手段

ceiling 訊號：

看到任一訊號、不是「再寫一條 hook」、是接受 hook 對這個錯誤層次無能為力、改設計 multi-pass review。

跟其他抽象層原則的關係

本卡是 #72 的 sibling / 補強 — #72 推 L3-L5 結構性對策最強、本卡指出 L5 也有 ceiling、不是萬能。組合解：字面用 L5 hook、行為用 L4 pair + multi-pass。#124 進一步把行為層細分出 emergence 子類、補上對應 enforcement 時機。

套用到本系統的 case

Case 1：卡片系統本身

mdtools fmt --fix 是 hook（字面）— 處理 frontmatter、table 對齊、檔名 slug。 卡片內容對不對、抽 meta 抽得對不對 = 行為錯誤 — 靠 spiral 浮現（#81）、不靠 hook。

Case 2：搜尋頁 bug

CI 跑 playwright = 字面測試（給定輸入、output 是否符合）。 但「filter mode 切換有沒有 silent failure」這個 bug 一開始連 test case 都沒列、是 user 回報才浮現 — multi-pass dogfood 才 catch 到。

Case 3：決策對話 collapse

Hook 寫不出「這個回應 collapse 到 yes/no」的規則（語意理解）。 靠 reference 的 self-check + dogfood 例子 + 對話中 user 反饋的 multi-pass 才能 catch。

每個 case 都驗證同一條：字面層工具有用、但 ceiling 明確；行為層需要 multi-pass、不靠攔截。

判讀徵兆

核心：驗證手段的 ROI = 跟錯誤層次對齊 × 不超出 ceiling。Hook 不會思考、所以只能擋字面；行為錯誤需要 multi-pass spiral、用每輪不同角度收斂、不靠單次攔截。試圖用 hook 蓋 spiral 該做的工作 = 假裝有保護、實際比沒保護更危險。

凡是教做事方法的東西（SKILL、playbook、methodology document、checklist）— 如果你認為 multi-pass refinement 是必要的、就要把它放在核心結構層（pillar、principle、step）、不是放在附帶段（appendix、tips、reminder、see also）。

放在 appendix = 結構暗示「optional、看心情選擇」 = 在 #72 高 ROI 無觸發 的結構壓力下、永遠被跳過。Pillar 層 = 結構性必跑、用結構強制行為、不靠紀律。

為什麼 pillar / appendix 的位置決定執行率

讀者看 SKILL / methodology 時、認知資源分配：

• Pillar / Core Principles：必讀、會內化、實作中會回想
• Steps / Reference：實作中翻
• Tips / Appendix / “See also”：第一次讀掃過、之後忘記

把 multi-pass review 放 appendix = 結構暗示「這是進階、可選」。即使內容寫得很詳細、結構訊號蓋過內容。

對比放 pillar：每次接觸 SKILL、第一眼看到 4-5 個 pillar 中包含 “Multi-pass Refinement” — 結構性提示「這跟其他 pillar 同樣重要」。

各 methodology 的 pillar / appendix 切分

實際 methodology 文件的 pillar 應該包含 multi-pass、appendix 應該避免：

每個 methodology 的設計都該檢查：multi-pass 是 pillar 還是 appendix？

如何識別「該升 pillar 但被當 appendix」

訊號：

每個訊號都是 multi-pass 的位置太低、結構壓力把它當作 optional。

升 pillar 後的設計：四個必要元素

把 multi-pass 升成 pillar、需要含這四個元素才完整：

1. 明示「第 1 輪不追求完美」

寫在 pillar 內容、第一句就講：「第 1 輪不要追求 perfect、預期會有未發現問題、設計第 2 輪去 catch」。

去掉「第 1 輪該寫對」的隱含預設、釋放認知資源。

2. 列出 N 輪的 frame 清單

每輪用什麼 frame、catch 什麼。例：

1輪 1：生成 — idea → 字
2輪 2：對意圖 — 跟原意對齊嗎
3輪 3：機會成本語氣 — 絕對主義詞翻成 trade-off
4輪 4：grep-ability — 關鍵字前置嗎
5輪 5：反例 / 邊界 — 何時不適用寫了嗎

3. 何時可跳輪

不是所有情境都跑全輪。寫清楚「跳輪的合理情境」、避免「跑全輪 = 過度工程」的反彈。

4. 跨 frame 的不可替代性

明示：輪 N 不能用「再跑一次輪 N-1」取代 — 不同 frame 才能 catch 不同層。重複同 frame = 同類錯一直 miss。

反模式：「我自己會 review」當 pillar 替代

1不該寫：「請務必在送出前自行 review。」
2應該寫：「此 methodology 的第 N 個 pillar 是 Multi-pass Review、含 1-5 輪 frame：⋯⋯」

「自行 review」= L1 紀律（#72）= 預期失敗。

「列入 pillar + 列輪次 + 列 checklist」= L3-L5 結構性對策 = 結構強制執行。

套用到本系統的具體 case

Case 1：requirement-protocol skill

• 現況：3 大支柱 + 6 大原則、multi-pass 散在「2 次門檻」「漸進驗證」「revert checkpoint」三條原則裡、沒明示
• 應該：升第 4 支柱「Multi-pass Refinement」、把散落的多輪意涵集中

Case 2：compositional-writing skill

• 現況：3 大支柱 + 5 大原則、各 reference 結尾有「self-check」段（部分 multi-pass 跡象）
• 應該：升第 6 原則「Re-read Pass」、引用 #83 的 5 輪 frame、各 reference 加「第 2 輪 review checklist」

Case 3：frontend-with-playwright skill

• 現況：「漸進驗證」原則含 multi-pass、但跟「dogfood / 多輪測試」沒串連
• 應該：補抽象層原則段、明示 multi-pass 跨「漸進驗證 → playwright dogfood → production observation」是同一條 spiral

跟其他抽象層原則的關係

判讀徵兆

核心：Methodology 設計的 pillar / appendix 切分不是內容深淺問題、是執行率問題。Pillar 層必跑、appendix 層不跑。把 multi-pass 視為「附帶」= 結構性確保它不被執行。真正必要的東西要升結構、不能藏在末尾。

當系統能力不滿足使用者預期（capability gap）時、對策有三層階梯、依序評估：

預設順序：L1 → L2 → L3、依「成本最低先解」。不必每次跳到 L3 — L3 是最完整但也最貴、L1 在很多情境就夠。

為什麼有階梯：cost-coverage trade-off 是真實的

直覺反應遇到 capability gap 都想 L3「從根解決」。但 L3 的成本通常 10-100x 於 L1、覆蓋率提升可能只是 80% → 99%、邊際 ROI 低。

實際分布：

• 50% case：L1 就夠（gap 是「使用者誤解」、講清楚就好）
• 30% case：L2 解掉（gap 是「engine 差一步運算」、補一層 close）
• 20% case：必須 L3（gap 是「engine 模型錯位」、補不夠、要重來）

先試 L1、再試 L2、最後 L3 = 用真實 ROI 排序、不是用「完美主義」排序。

三層的判讀

L1：expectation alignment

適合：

• Gap 是「使用者預期跟 system capability 對不齊」、不是「system 算錯」
• 使用者改變行為就能 close gap（打字方式、order operation、輸入格式）
• Production 真的有 capability、只是 affordance 不明顯

不適合：

• Gap 在 system 算錯、不是預期錯位
• 使用者無法配合（流量大、不可能教育每個 user）
• 訊息會被忽略（A/B test 證明 hint 沒人讀）

例：

L2：augmenting computation

適合：

• Engine 缺一層計算就能 close gap、額外計算不貴
• Client / proxy / wrapper 層可加運算、不動 engine
• 預期 query 量在 augment 計算容量內

不適合：

• 補強計算成本爆炸（dataset 大、O(N) per query）
• Augmenting 跟 engine 結果語意不一致（產生 ghost results）
• 需要兩 engine 同步狀態才正確

例：

L3：structural rebuild

適合：

• L1 / L2 都不夠、capability gap 持續引發痛苦
• Production scale 大、L1 教育成本爆 / L2 計算成本爆
• 系統還沒長太大、重 build 成本可承受
• 將來會反覆遇到同類 gap（一次重 build、長期解多個問題）

不適合：

• L1 / L2 還沒試
• Production scale 不可動 build pipeline / schema
• ROI 不確定（gap 影響範圍小、值得 L3 投入嗎？）

例：

從 L1 升級到 L2 / L3 的訊號

不是「永遠先 L1」、是「依訊號逐層升級」：

逐層升級 vs 一次跳 L3：前者是 #76 分批 ship 的具體展現；後者是「便利驅動偏移」（#67） — 容易寫的選項是 L3「一勞永逸」、跟實際 ROI 不對齊。

從 L3 / L2 降級回 L1 的訊號

階梯不是只能升、也該能降 — L3 ship 後不該當「永久解」、是 ROI 動態的選擇。看到以下訊號、考慮降級：

為什麼降級難

升級有「使用者抱怨」當外部觸發、降級沒有 — 沒人抱怨「我們的 transformation 太多」。所以降級是典型的 #72 高 ROI 無觸發 工作、需要結構性 trigger：

• Periodic review（每季 review「我們還需要這個 L3 嗎」）
• Dependency upgrade event（升級觸發「L3 還相容嗎、還必要嗎」）
• Maintenance cost log（紀錄 L3 修了 N 次、累積到 threshold 觸發 review）

Pruning 是正常 lifecycle

降級不是「我們之前做錯」、是「ROI 變化、調整」。L3 在 ship 當下是最佳解、現在不是了 — 接受 capability gap 對策也會過時、跟其他工程決策同。

階梯 vs 疊加：跟 #75 的差別

#75 主策略 + 補強策略 講的是多策略疊加在不同層（structural + UX 並用）。本卡講的是同一個 gap 上、選哪一層（L1 vs L2 vs L3 通常選一個）。

兩卡互補：

• #75：選了 L3 後、要不要再加 L1 UX hint 當補強？（疊加維度）
• #86（本卡）：先試 L1 還是直接 L3？（階梯維度）

實際 case 通常兩條都用：先 #86 選層級、再 #75 看要不要疊加。

反模式

何時直接跳 L3

四類共通：L1 / L2 已知不夠、或 L3 真的最便宜。其他情境都該先試 L1。

跟其他抽象層原則的關係

判讀徵兆

核心：Capability gap 不是只有 L3 一條路 — L1 / L2 / L3 是 ROI 不同的三層階梯、依「成本最低先解」順序評估。「直接 L3」的便利感跟實際 ROI 反相關（#67）— 寫 L3 在白板上很爽、但通常 L1 / L2 已夠。

計算放哪裡有光譜、不是二元：

光譜兩端都有合理場景、不是「build-time 永遠贏」。選哪個位置依四軸：query 頻率 / dataset 大小 / freshness 需求 / build pipeline 複雜度。

build-time 的三個成本維度

直覺反應：「能 precompute 就 precompute、runtime 0 最好」。但這個直覺漏了三個維度：

1. Freshness 成本

Build-time 結果是 build 那一刻的 snapshot。dataset 改變後、結果直到下次 build 才 refresh。

• 適合 build-time：靜態 / 慢變的內容（blog post、product catalog）
• 不適合 build-time：頻繁更新（user posts、live data、search index over user content）

2. 儲存成本

Precompute N 種 query 的結果 = 存 N 份。當 query 是 open-ended（任意組合 filter / sort / search term）、N 是組合爆炸。

• 適合 build-time：closed-set（fixed list of routes、pre-defined search terms）
• 不適合 build-time：open-ended（任意 user input）

3. Pipeline 複雜度

Build-time 計算需要 build pipeline 配合 — 加一條規則 = 加一份 artifact、需要 CI 跑、版本管理、deployment 同步。

• 適合 build-time：已有 build pipeline、加一條規則便宜
• 不適合 build-time：純 dynamic system、加 build step = 引入新 infrastructure

四軸判準

評估某個計算該放哪一端：

軸 1：Query 頻率

• 高頻（同一 query 每秒被 call N 次）→ build-time 划算（一次算、N 次受益）
• 低頻（query 多樣、每個 query 唯一）→ runtime 划算（precompute 全部 = 浪費）

軸 2：Dataset 大小

• 小 dataset → 兩端都可以、依其他軸
• 大 dataset → build-time 的儲存成本爆炸、傾向 runtime / hybrid
• 超大 → 幾乎強制 runtime（即使 hot path 也 partial precompute）

軸 3：Freshness 需求

• 可接受 stale（小時 / 天） → build-time 可行
• 要近即時（分鐘級） → runtime 或 hybrid + invalidation
• 強即時（秒級） → 強制 runtime

軸 4：Build pipeline 複雜度

• 既有 pipeline 成熟 → 加 build-time step 便宜
• 沒 pipeline 或脆弱 → runtime 更實際（不引入新 infrastructure）

三段光譜的實例對照

Pure build-time

Hybrid hot-path

Pure runtime

兩極之間的決策：當不確定該選哪端

步驟 1：列「query frequency × dataset size」象限

步驟 2：套 freshness 限制

如果 freshness 需求高、把 build-time 列從候選移除（除非有 incremental build / invalidation 機制）。

步驟 3：看 build pipeline cost

如果 build-time 成本（新 step、新 artifact、新 deploy 流程）大於 runtime 成本（per query CPU）、選 runtime。

步驟 4：留 escape hatch

選了一端不代表永遠 — 設計 invalidation hook / runtime fallback、未來能重新平衡。

反模式

何時是「兩端都不對、要重思 problem」

跟其他抽象層原則的關係

判讀徵兆

核心：Build-time vs runtime 是光譜、不是二元 — 中間 hybrid 段是多數實務情境的最佳位置。「能 precompute 就 precompute」是便利驅動（#67）的口號、實際要套四軸（頻率 / 大小 / freshness / pipeline）才知道該放哪。

寫作 / UI 中的問題分三層、不同層需要不同修法：

核心：修視覺工具預設錯誤就在視覺層。當症狀其實來自語意 / 邏輯層、用視覺工具修 = 蓋掉表面、根因還在 + 作者誤以為解決了（false confidence、跟 #82 的 hook 心理同病）。

修法的順序是 深層 → 淺層：先問「是不是邏輯 / 語意層的下游症狀」、是的話改結構；確認純視覺、再用視覺工具。

為什麼視覺工具對語意 / 邏輯問題無能為力

視覺工具（CSS、emoji、顏色、字體、間距、圖示）的本質是 呈現層的調整 — 它能改變字怎麼顯示、不能改變字本身代表的概念。能改的、跟改不到的、有清楚的界線：

能改的（純呈現）：

• 文字在窄視窗會不會換行
• 兩個區塊的視覺距離
• 不同類型用什麼顏色標

改不到的（結構 / 語意 / 邏輯）：

• 兩個概念該不該擠在同一行（結構層）
• 用 emoji 區分是否足夠承載語意（語意層）
• 論證有沒有完整（邏輯層）

當作者試圖用視覺工具解語意 / 邏輯問題、結果是 症狀被表面平整、但下次同類問題會用新形狀冒出來 — 因為根因（概念混淆 / 結構錯位）沒動。

反模式：用視覺修補蓋住下游症狀

False confidence 比沒修更危險

修了 CSS 之後、心理上會覺得「處理完了」。實際上 CSS 只擋了表面斷行、語意混淆照舊存在 — 但作者不再警覺、因為「我修過了」。

下一個讀者在不同 viewport / 不同設備 / 用螢幕閱讀器時、同樣的語意問題會用不同形狀重新出現（換行錯位、TTS 讀錯、複製貼上格式跑掉）。

第二行是最危險組合 — 跟 #82 的「Hook 抓不到的範圍誤以為有保護」同病。

症狀堆疊：「再加一條 CSS 規則」永遠補不完

視覺修補的直覺反應是「加一條規則」。但語意 / 邏輯下游的症狀無限多、規則永遠補不完。實際軌跡：

 1emoji 在窄 viewport 斷行
 2  → 加 white-space: nowrap
 3  → 文字溢出容器
 4  → 加 overflow: hidden
 5  → 文字被截斷看不見
 6  → 加 text-overflow: ellipsis
 7  → 螢幕閱讀器讀出「...」沒語意
 8  → 加 aria-label 補語意
 9  → 翻譯版本 aria-label 沒翻
10  → ...

每加一層 CSS、根因（兩個概念擠在一行）更深埋、修起來更貴。

→ CSS 規則膨脹是「用錯工具」的訊號、不是「規則寫得不夠細」的訊號。跟 #82 的 hook 規則膨脹同骨。

三層優先序：邏輯 → 語意 → 視覺

為什麼是這個順序

深層問題的影響範圍大、修不到根因的代價高。所以修法順序是先問深層、確認沒問題再修淺層。

修法的順序

 1看到症狀
 2   ↓
 3這是邏輯層問題嗎？（兩個獨立概念被擠在一起？論證有缺口？）
 4   是 → 重新分概念 / 補論證、結構改了之後語意 / 視覺問題自然消失
 5   否 → 下一層
 6   ↓
 7這是語意層問題嗎？（依賴視覺標記傳達唯一資訊？emoji 是唯一區分？）
 8   是 → 改表達結構、加文本標籤、用列表 / 分段
 9   否 → 下一層
10   ↓
11純視覺問題（容器寬度、字體大小、顏色對比）
12   是 → CSS / media query / 渲染配置

反向（從視覺往邏輯推）會 false confidence：先用 CSS 補了、表面平整、誤以為解決了、下次換 context 復發。

何時視覺修補真的足夠

某些情境純視覺就夠、用 CSS 是對的：

五類共通：內容本身沒爭議、只是顯示方式要調。其他情境視覺工具都會在某個時點走到 ceiling。

識別 ceiling：什麼時候該換手段

ceiling 訊號：

看到任一訊號、不是「再加一條 CSS / 換個 emoji」、是 接受視覺工具對這個層次的問題無能為力、改修結構。

跟其他抽象層原則的關係

本卡是 #82 的 sibling — 兩者都在說「工具有能擋的層 / 擋不到的層、超出 ceiling 是 false confidence」。組合理解：

套用到本系統的 case

Case 1：blog 文章 mermaid + emoji 圖例

寫 git rebase 搬部分檔案 文章時、用 mermaid gitGraph 配 emoji 圖例：

1> 🟢 HIGHLIGHT = 接收檔案變更的目標 commit（A）
2> 🔴 REVERSE = 含有不該屬於它的檔案變更的 commit（C）

某 viewport 下 emoji 跟文字之間斷行錯位、🔴 在前一行、REVERSE = … 在下一行。

第一直覺（錯）：修 emoji 渲染、加 white-space: nowrap。

追問層次：

• 視覺層：emoji 斷行 → 改 CSS 可以擋
• 語意層：HIGHLIGHT 跟 REVERSE 是兩個獨立概念、被擠在 > 引用區塊 的兩行 + 用 emoji 作為唯一區分 — emoji 不渲染（終端 / 老瀏覽器）就完全失語意
• 邏輯層：兩個獨立概念本就不該擠在引用區塊裡、引用區塊的語意是「附加說明」、但兩個概念都是主要資訊

根因在邏輯層：兩個概念該分開承載。

正解：拆成獨立列表項、每項獨立一個概念：

1**四個 commit 的角色**：
2
3- **A**（接收目標）：commit C 中對檔案的修訂應該屬於這裡
4- **C**（變更來源）：同時改了目標檔案和其他 6 個檔案

修了之後、emoji 斷行、aria-label、複製貼上格式、螢幕閱讀器順序等所有下游症狀同時消失 — 因為根因被處理了。

Case 2：mermaid gitGraph type 顏色設定

跟 Case 1 同篇文章的另一個議題：mermaid 的 type: HIGHLIGHT / type: REVERSE 自訂顏色不渲染（mermaid_gitgraph_type_color_config）。

這個 是 純視覺問題 — 內容本身沒爭議、只是 mermaid themeVariables 缺配置。修 CSS / themeVariables 是對的。

兩個議題在同一篇文章、但層次不同 — 一個是邏輯層下游症狀（誤判為視覺）、一個是真視覺問題（CSS 修對位）。判讀層次比修法重要。

Case 3：multi-pass review 的層次盲點

#83 的 5 輪 frame（生成 / 意圖 / 語氣 / grep / 反例）是 horizontal — 同一份文字、5 個視角輪流看。但這 5 輪都可能落在同一個 vertical layer（例如全部在看視覺層）、漏掉語意 / 邏輯層。

本卡補的是垂直軸：每輪 frame 內、要意識到問題在哪一層。第 1 輪生成可能寫出語意混淆、第 2 輪對意圖如果只看視覺呈現、整個 review 就停在視覺層。

實際軌跡：blog 文章寫完跑了 #83 的多輪 review、catch 到 emoji 斷行（視覺層）、但沒 catch 到 HIGHLIGHT/REVERSE 概念混淆（語意層）— 因為每輪 frame 都沒把 layer 當成獨立檢查維度。

判讀徵兆

核心：視覺工具的 ROI = 跟問題層次對齊 × 不超出 ceiling。CSS / emoji / 顏色不會理解語意、所以只能擋呈現；語意 / 邏輯問題需要改結構 / 改概念分組、不靠視覺工具。試圖用視覺工具蓋語意 / 邏輯問題 = 假裝修了、實際比沒修更危險（false confidence 阻止下次警覺）。

「Collapse」是同骨 pattern — 高維選擇空間被便利驅動 reduce 到最少格子、且這個 reduction 看似中性、實際藏掉維度。三個 surface 各自的 collapse 典型：

三者共通結構：

1. 真實選擇空間是 多維 / 多選
2. 預設行為把它 reduce 到 1-2 維 / 1 選
3. 這個 reduction 看起來「合理 / 簡潔 / 合規」、不被覺察是 collapse
4. 後果是 使用者 / 讀者被塞進最窄格子、要破格才能表達或回應

為什麼 Collapse 是 default、不是 violation

跟其他「明確違規」不同、collapse 預設 合規 — 沒有規則禁止 yes/no 問句、沒有規則禁止單一 framing、沒有規則禁止單一策略推薦。這是 collapse 最危險的特性：

Collapse 是隱形預設、原因在 對比標的不存在於眼前。Yes/No 問句要 collapse 到 1 bit、需要使用者已經想過五維 collapse；五維 collapse 要看出、需要使用者已經理解 #79 五維框架；framing collapse 要看出、需要連讀多篇且預期有變體。沒有 對照原型 在眼前、collapse 看起來就是「正常」。

Collapse 不是「該消除」、是「該變顯性」

對策不是去除 collapse — 多數情境下使用者 / 讀者確實受益於 reduction（不用每次都展開五維、不用每篇 cadence 都換）。對策是 讓 collapse 變顯性：

顯性化的代價是 寫的人多打字 / 多設計、得益是 接收方知道自由度在哪、可以選擇接受預設或破格。預設展開、選窄格要證明 — 跟 #78「不互斥是預設」同條結構。

跨 surface 的判讀通則

判斷某個情境是不是 collapse、不是看「有沒有違規」、是問三個 diagnostic：

1. 真實選擇空間是幾維 / 幾選？ — 如果 ≥ 3、reduce 到 1-2 就是 collapse
2. 這個 reduction 是設計選擇還是預設? — 設計選擇會有「為什麼選窄格」的論述、預設沒有
3. 接收方破格的成本是多少? — 破格要破壞既有對話 / review / commit 結構就是高成本、表示 collapse 藏得深

三個 diagnostic 全 yes、就是隱形 collapse。

反模式

跟其他抽象層原則的關係

判讀徵兆

核心：Collapse 是高維空間預設被 reduce 到 1-2 維、看似中性、實際藏掉維度。三個 surface（decision / dialogue / output）有同骨 collapse pattern、都被「便利 / 合規 / 簡潔」驅動、都需要顯性化。對策不是消除 collapse、是讓設計者主動選擇要 collapse 哪一維、預設展開、選窄格要證明。

寫作 review 完整性的本質是 多軸交集、不是 單軸深度。七個軸已經從前面卡片浮現、缺任一軸就會 systematic miss 對應類型的問題：

七軸正交：每個軸獨立解一類盲點、不重疊；缺任一軸都會 systematic miss 對應類型問題。

為什麼是多軸、不是單軸越做越深

單軸越做越深的失敗模式：

1. Frame 軸跑 10 輪、不換 instance 軸：同一 reviewer 跑 10 輪、catch 的問題仍高度相關（#114 已點出）
2. Instance 軸開 10 個 reviewer、不換 frame 軸：10 個 reviewer 都跑「規則 check」這個 frame、catch 的盲點相同
3. Frame + Instance 都做、不管 Surface 軸：Body review 通過、但 title / description 沒被審、搜尋入口失效
4. Surface 都做、不管 Cadence 軸：51 篇個別合規、連讀預期化
5. Cadence 軸有抽樣、Timing 軸放在 batch 後：抽樣等於 batch 後 review、修正成本 N 倍

七軸缺任一條、就有對應類型違規逃過 review。

多軸是預設、單軸是 collapse

跟 #125 Collapse 是隱形預設 同骨 — 把 review 設計 collapse 到單軸是預設行為（最便利）、但 collapse 掉的軸對應的違規會 systematic miss。

預設展開七軸、選窄做要證明 — 跟 #78 / #79 / #80 / #125 同條結構。

Review 設計時的 enumerate 紀律

設計新的 review 流程（人類 / agent / 自動化）時、不該只看「捕獲哪些違規」、要列七軸覆蓋狀況：

七題都回答後、再判斷該不該補軸。如果某軸沒覆蓋、不一定要補（cost vs risk）、但要 知道沒覆蓋對應什麼盲點。

Cadence + Timing 軸 dogfood (2026-05-18)

4 篇 deep article batch 驗證 cadence + timing 兩軸的設計、不靠 reviewer 補、是靠 stage 2 寫作流程內抽樣：

• Cadence 軸：4 篇 pilot phase 主動規劃 4 種 framing variant、跨檔 cadence audit 顯示「任一缺失」collapse 族 0/4、entry framing 種類 4 種
• Timing 軸：每篇寫作前做 cadence check（生成中 checkpoint）、不等 batch 完成後 reviewer；修正成本 ~5 分鐘 / 篇 vs 前批 batch 後 polish ~30-60 分鐘

N=5 full-threshold 補強驗證（同日第二批）：再跑 5 篇 PostgreSQL sub-tool deep article、用 5 種 variant 覆蓋 同 vendor 同 audience 的 cadence collapse 最高風險場景；結果 5/5 framing 全錯開、過渡詞密度 0、cadence collapse 0/5。確認 Cadence 軸 + Timing 軸 不靠 sample size、靠 stage 0 variant 規劃。

詳細數據見 #122 cadence dogfood evidence 跟 #124 dogfood — 兩軸都不必加 reviewer instance、是 Stage 2 寫作流程設計即可解。

七軸不是隨機湊出來、有結構

七軸可以再 group 成三個 上位 axis：

四上位 axis 各自獨立、合起來覆蓋 review 設計的所有 surface。當 review 出問題、依四上位 axis 找根因比依七子軸快。

反模式

跟其他抽象層原則的關係

判讀徵兆

核心：寫作 review 完整性是七軸交集、不是單軸深度；缺軸不缺深度。設計 review 流程時 enumerate 七軸覆蓋狀況、預設展開、選窄要證明；當 review 報告漏抓 systematic 違規、查的不是「再加一輪」、是「哪一軸沒覆蓋」。

跨 X process content（migration / upgrade / rollout / 演練 / playbook）的結構不是 universal、由 source 跟 target 之間的 差異維度組合 決定。固定套「6-phase playbook」「6-section deep article」會在 結構錯位 的場景失效。

實證：6 種 migration / process type 產出 6 種不同結構：

6 種結構是 常見 type、不是窮盡分類；source / target 配對可能同時屬多 type（多軸 High）、或不屬任一 type（6 維皆 Medium）— 處理規則見「多重歸類跟 tie-breaking」段。本卡前身是「最大差異維度決定結構」+ 5 維 audit、Redis re-sharding dogfood 揭露 data topology 是漏掉的第 6 維、Type F 是對應的第 6 type；本卡擴張為 6 維 audit + 6 type。

為什麼 universal phased 模板會失效

寫第一篇 migration playbook 時自然會想：「6 phase 是 migration 的標準結構吧」 — 套到 drop-in compatible migration 後發現 80% phase 不需要、文章變成「為了 phase 而 phase」；套到 paradigm shift 後發現 phased 假設 線性收斂、實際是 永遠混合架構、phased 模板強迫一個 不存在 的「cleanup phase」。

Universal phased 失效的三個機制：

1. Schema 差不顯著時、phased 多數 phase 變空白：drop-in compatible（如 Redis → DragonflyDB）的「Schema translation phase」內容空、強寫變廢話
2. Operational 差是主軸時、phased 把 operational redesign 壓進「phase 1」變太薄：PostgreSQL → Aurora 的 operational model 重設計 是核心、不該壓在一個 phase
3. Paradigm 差時、phased 假設 source 完全消失：Kafka ↔ NATS 是 永遠共存、phased cleanup phase 假設不存在

→ 結構必須跟差異維度對位、不能反向假設。

Diff dimension audit：寫作前的必要 step

寫 process content 前先做 audit、列出 source 跟 target 在 6 個維度的差異程度：

主導差異維度對映常見 type：

• Schema = High（其他 Low） → Type A phased rule translation
• Operational = High（其他 Low） → Type C operational redesign hybrid
• Paradigm = High → Type E partial + 混合架構
• Components = High（一站式 → multi-tool） → Type D parallel streams
• Topology = High（其他 Low） → Type F topology re-layout（見 #128）
• 全 Low → Type B drop-in、6-section + audit prefix

第 6 維 Data topology 是後續從 Redis cluster re-sharding dogfood 浮現補位、見 #128 Data topology 是 process content 的第 6 audit 維度；本卡原為 5 維 audit、被第二輪 batch evidence 揭露盲點後擴張為 6 維。

多重歸類跟 tie-breaking

實際 source / target 配對 很少 完美對映單一 type；常見情境跟處理規則：

關鍵原則：主導維度決定主結構、其他高維度獨立加段、不強迫單一 type 標籤。Backlog 的「Type A/D 混合」「Type B/D 混合」標示是 維度組合 的簡記、不是承認 5 type 互斥失效；下表多重歸類處理規則才是正式判讀。

6 type 是 axis-aligned simplification、非窮盡

本卡 6 type 來自兩輪 migration playbook 的 dogfood 觀察（第一輪 5 篇 → Type A-E、第二輪 Redis cluster re-sharding → Type F）、是 已浮現的 type、不是 涵蓋所有 migration 的完備分類。已知漏類至少 3 種：

未來累積更多 migration playbook 後、可能浮現第 7-9 type（identity / consistency / residency 候選 — 對應 #128 跟 self-aware limitation update 揭露的候選軸）、或對 6 type 重構。本卡的 type 集合是 open、不是 closed。

6 種結構的 anatomy

**「結構 differentiator」**是本系列引入的概念：每篇 process content 在開頭加一段、明示這篇用什麼結構、跟其他同 category content 的結構差異在哪。功能類似 type signature — 讓讀者一開始就知道接下來的章節組織方式、避免套錯預期。例：drop-in migration 的「結構 differentiator」段會說「跟 phased migration 對照、本篇是 6-section + audit、不是 6-phase」。

Type A：Phased translation（schema 差為主）

1Phase 0 audit → Phase 1 schema 對位 → Phase 2 translation
2→ Phase 3 parallel run → Phase 4 cutover → Phase 5 cleanup

特徵：

• 線性 流程、phase 之間有 dependency
• 每 phase 有獨立 回退邊界
• Schema translation 是工作量主軸（4-12 週）

適用：Splunk → Elastic / Datadog APM → New Relic / MySQL → Postgres

Type B：6-section + audit prefix（drop-in compatible）

1為什麼遷 → 結構 differentiator → 相容性 audit
2→ Step-by-step cutover → 故障演練 → Capacity → 整合

特徵：

• 接近 deep article 6-section
• 多一段 相容性 audit（在 cutover 前列出風險點）
• 不需要 phased、單次 cutover

適用：Redis → DragonflyDB / OpenJDK → Adoptium / MariaDB → MySQL（部分版本）

Type C：Operational redesign hybrid

1為什麼遷 → 結構 differentiator → Operational redesign 對位
2→ 4-phase operational migration（Phase 0 audit + 3 active phase）→ Drop-in cutover → 故障演練 → Capacity → 整合

特徵：

• application code 不變、operational model 全換
• operational 表格對位 是內容主軸
• Cutover 本身簡單（protocol 相容）、operational 準備複雜

適用：PostgreSQL → Aurora / Self-managed Redis → ElastiCache / Self-managed Kafka → MSK

Type D：Parallel streams（multi-tool 拆分）

1為什麼遷 → 五個責任、五個 component → 5 parallel migration stream
2→ Stream-level audit / deploy / dual-ship / cutover → 故障演練 → Capacity → 整合

特徵：

• source 一站式、target N 個專責 component
• 每個 stream 獨立 audit / deploy / cutover、stream 間少 dependency
• 整體不是線性、是 staggered parallel

適用：Datadog → Grafana Stack / Splunk → Elastic + Tines + PagerDuty / Atlassian Suite → 各 specialized tool

Type E：Partial + 混合架構（paradigm shift）

1「不是 migration、是 paradigm 重設計」→ Paradigm 對位
2→ 什麼情境真的能換 → Application 重設計 → 部分 stream cutover → 長期混合架構

特徵：

• 不存在「complete migration」、是 按 use case 拆分 + 共存
• application 模式重設計（不是 SDK 換）
• 混合架構是 long-term default

適用：Kafka ↔ NATS / REST → gRPC / SQL → NoSQL / VM → Serverless

Type F：Topology re-layout（data topology = High）

1為什麼 re-layout → 結構 differentiator（re-layout 不是 migration）
2→ Pre-layout analysis（topology audit）→ Re-layout 機制
3→ Execution flow（per-step + rollback boundary）
4→ 故障演練 → Capacity / cost → 整合

特徵：

• Source / target 多數是 同 cluster 不同 state、不是跨 vendor
• 主軸是 topology audit + 重劃機制、不是 schema translation / paradigm shift
• Pre-layout analysis（識別 hot key / 當前 distribution）是 Type F 的核心 audit 段
• Execution flow per-step、含 rollback boundary

適用：Redis cluster re-sharding / PostgreSQL partition redesign / Kafka topic re-partitioning / Cassandra keyspace re-balance / 加 region / multi-master rollout

詳細 audit dimension 跟 sub-dimension 見 #128 Data topology 是 process content 的第 6 audit 維度。

跟 deep article methodology 的關係

Deep article methodology 的 6-section structure（問題情境 → 概念 → 配置 → 演練 → 容量 → 整合）是 single feature implementation 的模板、不是 cross-vendor process 的模板。Migration playbook 是 新 content category、需要自己的 methodology。

兩者關係：

• Single feature deep article：6-section、200-400 行、focused on how to implement / debug feature X
• Migration playbook：6 種 structure（依 diff dimension）、200-400 行 / 篇、focused on how to move from A to B
• 共同：問題情境 / 故障演練 / 容量 / 整合段；差異：中間「process / structure」段

寫前的 content category 判讀 是新方法論議題、不是 deep article methodology 涵蓋。

反模式

跟其他抽象層原則的關係

判讀徵兆

核心：Process content 的結構由 source / target 差異維度組合 決定、不是 universal phased / 6-section 模板。寫作前必須跑 6 維 diff dimension audit（schema / operational / paradigm / components / application change / data topology）、選對應主結構、其他高維度獨立加段；跳過 audit 會套錯模板、phase 變空白或 process 強行線性。

Self-aware limitation：本卡的 sample-driven over-fit 風險

本卡 5 type 來自 5 篇 migration playbook 的 dogfood 觀察、本身就是 N=5 sample 推導出 5 type taxonomy — 跟本卡批判的「universal phased 模板」「#122 cadence collapse」「#125 reduce 多維到單格」是 同骨錯誤。

本卡是 current best understanding、不是 已驗證的完備理論。Tripwire：

• 若下一輪 migration batch 浮現 無法歸進現有 5 type 的新 structure、應該擴充 type 集合而不是強行歸類
• 若同一 source/target 配對出現 結構翻轉（例 PostgreSQL → CockroachDB 在不同 application context 走不同主結構）、應該檢視 主導維度 規則是否需要動態化
• 若 type 數量擴張到 8+、應該評估是否該重構為 維度 × 維度 grid 而不是 type list

承認 limitation 本身是 dogfood — #122 cadence 同質化 講「natural attractor 不規劃就 collapse」、本卡的 5 type 就是 5 個 sample 的 natural attractor；不在卡內承認、就重複了 #125 隱形預設 的 collapse pattern。本段是 self-correction、不是 disclaimer。

Update（2026-05-19）：第二輪 migration batch 驗證 limitation

第二輪 migration batch（5 篇）跑完、self-aware limitation 三項預測得到驗證：

新發現（不在 self-aware limitation 預測內、需要後續處理）：

• 新 audit 維度浮現：re-sharding 揭露「data topology」是 5 維沒有的軸；audit 擴張為 6 維（加 topology 軸）已執行、見 #128 Data topology 是 process content 的第 6 audit 維度 + 本卡 audit table 新加 row 跟 Type F anatomy
• 「為什麼這篇不套」是漏類文章的好結構模板：major-version-upgrade 跟 cluster-resharding 都用這個 frame 開頭、明示跟 5 type 的邊界
• 「高維度獨立段」對照表自然在 multi-axis 文章浮現（cockroachdb 篇）— 應該升級為 multi-axis migration 的標準結構元素

Update（2026-05-19 第三輪 4-reviewer audit 後）：6 維擴張的未解結構性質疑

第三輪 audit 揭露本卡擴 6 維 + Type F 仍有 6 項未解結構性 issue。完整列表跟 acknowledgment 見 #128 Self-aware limitation 段、本卡這裡 cross-reference：

1. 6 維非窮盡：identity / consistency / residency 三軸候選
2. Type F 跟 Type B 結構重疊度高：實質差異只 2 段、可能下次 evolution 降為 Type B variant
3. 「不需要 parallel run」claim 部分不成立（multi-region rollout 例外）
4. 主導維度優先序是 audience-dependent heuristic、非 universal
5. 「topology 不能塞進既有 5 維」拒絕理由依賴 narrow 既有 5 維定義
6. 既有 5 篇 playbook 沒 retroactive audit（silent grandfathering）

本卡的 6 type / 6 維框架是 current best understanding、不是 final taxonomy；累積到 10+ migration playbook 後可能觸發 retroactive audit + framework restructure。

Process content 的 diff dimension audit 原本 5 維 — schema / operational / paradigm / components / application change — 漏了 data topology 這軸。Topology 是 資料在 cluster / partition / region 之間的分佈拓樸、跟既有 5 維任一個都不對等：

Data topology 是 資料分佈 層級的概念 — 跟資料結構（schema）、運維機制（operational）、抽象模型（paradigm）、組件數量（components）、application code 改動量（application change）並列為第 6 軸；topology 變動時其他 5 維可能完全不變、但 資料在 cluster / partition / region 之間的擺放方式 改變、需要獨立的結構處理。

擴 audit 到 6 維、新增 Type F「Topology re-layout」 結構對映 topology 高差異 的 process content。

Topology 的 5 個 sub-dimension

不同 source/target 配對對 topology 的影響不同、用 5 sub-dimension 描述具體變化：

任一 sub-dimension 變動就構成 topology layout 變動；多個 sub-dimension 同時變更（如「sharding strategy + region distribution 同時改」）是 complex topology migration、結構複雜度高。

為什麼 topology 不能塞進既有 5 維

Reviewer 質疑：為什麼不直接歸進 operational 或 paradigm？三個拒絕理由：

1. Schema 不變但 topology 變：PostgreSQL partition strategy 改（monthly → daily）— schema 完全相同、partition boundary 重劃；歸 Schema 維度錯位
2. Operational stack 不變但 topology 變：Redis cluster 加 node 重分 slot — Sentinel / monitoring / backup 不變、純粹是 slot mapping 重劃；歸 Operational 維度太寬
3. Paradigm 不變但 topology 變：Cassandra 從 single DC 加到 multi-DC — 同 distributed DB paradigm、co-location / replication topology 變；歸 Paradigm 維度誤導
4. Components 不變但 topology 變：Kafka topic re-partition（10 partitions → 100）— 同 1 個 cluster、partition count 變；歸 Components 維度錯位

Topology 是 獨立的問題軸、5 維 audit 漏掉時會誤判結構。

觸發 Type F 的情境

多數 Type F 場景是 同 vendor — 跟 #127 Type A-E 預設「跨 vendor」對應、Type F 是 同 vendor 內 topology 重劃。

6 維 audit decision rule（updated）

擴 audit 到 6 維後、type 對映規則更新：

主導維度判讀的優先序也擴張：Schema > Paradigm > Operational > Topology > Components。Topology 在 schema / paradigm / operational 之後、components 之前 — 因為 topology 對讀者 conceptual impact 通常比 components 拆分大、但比 schema / paradigm 小。

Type F「Topology re-layout」結構 anatomy

從 Redis cluster re-sharding 抽出的標準形態：

11. 為什麼 re-layout（4-N 種 driver）
22. 結構 differentiator（re-layout 不是 migration）
33. Pre-layout analysis（current topology audit / hot key / slot 分佈）
44. Re-layout 機制（slot migration / partition split / shard rebalance）
55. Execution flow（per-step、含 rollback boundary）
66. Production 故障演練
77. Capacity / cost
88. 整合 / 下一步

7-9 章節、200-260 行。三個 新元素 是 Type F 的核心承擔：

• Pre-layout analysis 段：在執行前列出當前 topology（slot 分佈 / hot key / replica lag / partition imbalance）、決定 re-layout 的範圍跟順序；缺這段、後續執行階段沒 baseline 可比、failure 偵測延遲
• Re-layout 機制段：解釋 vendor 的 slot migration / partition split / shard rebalance protocol —讀者要理解 vendor 內部機制才能預估 latency / locking / atomicity 邊界
• Execution flow per-step + rollback boundary：跟 Type A 的 phased 對照、Type F per-step 粒度更細（單 slot migration vs 整個 phase）、每 step 都要明示 能否回退、回退時資料狀態

跟 Type B 對照、Type F 多了「topology audit」段、Step-by-step 比 Type B 細（per-step 不是 per-cutover）；跟 Type A phased 對照、Type F 多數情境不需要 schema translation / parallel run / cleanup phase（source / target 同 cluster）；但 multi-region rollout 子情境例外、仍需 parallel run（兩 region 同跑後切流量）— 此時 Type F + Type A parallel run 段組合應用、見「多重歸類」規則。

注意 anatomy 列 8 row 是 規範形態、不是強制機械對映 — 實作上「結構 differentiator」+「pre-layout analysis」段可 inline 到開頭 audit 段（如 Redis cluster re-sharding 的「Source = Target，但 topology 重劃」段內聯處理）、實作 H2 數可能比 anatomy 列 row 少 1-2 個。

Production 反模式

跟其他抽象層原則的關係

判讀徵兆

核心：5 維 audit 漏 topology 是初始框架的盲點；topology 是 資料分佈 而非 資料結構 / 元件 / 抽象、需要獨立 audit 軸。Type F「Topology re-layout」對映 topology = High 的 process content、跟 Type A-E 並列；多軸 High 配對按 #127 多重歸類規則處理。

Self-aware limitation：本卡的 6 個未解結構性質疑

第二輪 4-reviewer audit 揭露 6 項結構性 issue、本卡選擇 meta-acknowledgment（記錄）而非 substantive restructure（重寫）— 跟 #127 self-aware limitation spirit 一致：

1. 6 維仍可能漏類：reviewer 提 identity / authorization / consistency / transactional / data residency 三軸候選；本卡確認 6 維是 current best understanding、不是窮盡；下一輪 batch 跑前優先驗證這些候選軸是否真的獨立
2. Type F 跟 Type B 結構重疊度高：anatomy 8 row 中 6 row 跟 Type B 對齊、實質差異在「pre-layout analysis + re-layout 機制」兩段；可能下次 evolution 是 Type B 的 variant 而非並列 type；保留現狀因為「同 cluster」邊界對讀者區分有用
3. 「不需要 parallel run」claim 部分不成立：multi-region rollout 子情境仍需 parallel run（兩 region 同跑然後切流量）— anatomy 已加註此例外、跟「多重歸類」規則組合應用
4. 主導維度優先序是 audience-dependent heuristic：DBA 視角 Topology 可能 > Operational、application developer 視角 Schema > Paradigm；當前 Schema > Paradigm > Operational > Topology > Components 預設是「跨 audience 平均」、非 universal；reviewer 識別此 stipulation 性質
5. 「topology 不能塞進既有 5 維」拒絕理由的窄定義依賴：4 個拒絕點都靠 narrow 既有 5 維定義成立；換個合理定義（如「component = 任何 cluster-internal primitive、包含 partition」）topology 跟 components 邊界會 collapse；保留現狀因為當前定義對寫作判讀有用
6. 既有 5 篇 playbook 沒 retroactive audit：6 維框架 retroactively 對既有 Type A-E 文章未重審；Splunk → Elastic / Datadog → Grafana / Postgres → Aurora 按 6 維可能變 multi-axis；這是已知 silent grandfathering、不是清白「擴張」

下一輪 batch trigger：

• 寫 1-2 篇 Type F dogfood 驗證 anatomy 通用性（Cassandra re-balance / PG partition redesign 是候選）
• 若浮現 Type F 跟 Type B 結構真同構、考慮降級為 variant
• 若浮現 identity / consistency / residency 真的獨立軸、再擴 audit 到 7 維
• 既有 5 篇 retroactive audit 在累積到 10+ migration playbook 後做、單獨成 retrospective report

Update（2026-05-19 第三輪 migration batch 後）：4 條 tripwire 全驗證

第三輪 migration batch（5 篇）執行了上述 4 條 trigger、各自結果：

3 軸候選驗證 detail：

• Identity axis：Vault → AWS Secrets Manager 45% 工作量在 identity model 對位（Vault token vs IAM principal）、不歸 schema / operational / application change；驗證 identity 可獨立發生 + 帶獨立工作量
• Consistency axis：DynamoDB strong → eventual 85% 工作量在 per-call-site contract review、不歸 paradigm / application change；驗證 consistency 可獨立發生 + 帶獨立工作量
• Residency axis：GDPR multi-region 40% 工作量在 compliance（DPIA / evidence collection / DPO sign-off）、reverse-constrain topology + operational + application；驗證 residency 不只是 driver、是 cross-cutting constraint

新浮現議題（不在原 tripwire 內）：

• Residency 是 cross-cutting constraint vs 獨立軸：reviewer 把 residency 歸為 driver、實證上是 cross-cutting constraint — 反向約束其他維度 + 帶獨立合規工作量；可能需要 constraint layer 概念跟 axis 並列
• Type F sub-type 浮現：multi-region rollout 跟 cluster re-sharding 是不同 sub-type；前者需 parallel run、後者不需；anatomy 在 sub-type 之間有差異