底層的心法（讀權威狀態、不靠肉眼）見 診斷心法，這篇是它在「程序 / 服務 / 狀態」這一類的具體招式。

程式活著沒：比對正確的行程名

判斷一個程式在不在，行程表是權威來源，pgrep / ps 是對的工具，但成敗在於比對正確的行程名（comm，行程表裡記的執行檔短名，可從 /proc/<pid>/comm 看）。一個實際的坑：某個桌面 shell（畫桌面 UI 的圖形程式，不是 bash/zsh 那種命令列 shell）的可執行檔叫 quickshell，但透過名為 qs 的 symlink 啟動時，它在行程表裡的 comm 是 qs。這時 pgrep quickshell 找不到，很容易誤判成程式掛了、甚至誤觸「重啟」而引發更大的問題，實際上它以 qs 這個名字好好跑著。

可靠的做法：

• 先確認實際的 comm 名：ps -eo pid,comm | grep -i <關鍵字>，或看你啟動它的實際指令。
• 用精確比對：pgrep -x <comm>（-x 要求完全相符），或 pgrep -af <pattern> 連完整命令列一起比對，避免被 symlink 名 / 縮寫名騙。
• 另一個 comm 的坑：kernel 把 comm 截在 15 字元（TASK_COMM_LEN），名字超過 15 字的程式用 pgrep -x <完整長名> 反而 miss——這時改用 pgrep -af <pattern> 比對完整命令列。
• 別用一個「你以為的名字」掃過去就下生死結論——行程表沒騙你，是查詢條件寫錯。

進程活著 ≠ 內部子系統活著

比對到了正確的 comm、pgrep 也有輸出，只證明「這個進程存在」，不證明「它內部在正常運作」。有一類故障是進程好端端活著（pgrep 找得到、STAT 是正常的 S、在 poll 等事件、CPU 不高），但它內部某個子系統已經 wedged——例如一個圖形 shell 的 QML scene 因為上游錯誤（渲染 pipeline 建失敗之類）某個物件沒建起來變 null，於是負責互動的模組全部失效。表現是 bar 還畫得出來、卻點不動，keybind 叫不出東西，但焦點視窗打字正常。這時 pgrep 會騙你說「在跑」。

這種情況權威來源不是行程表，是程式自己的 log，而且這種 log 常常不在 journalctl、也不在你猜的路徑，要用該程式專屬的 log 指令（例如某桌面 shell 的 <shell> -l）。log 裡的 TypeError: Cannot read property 'X' of null 這類訊息，才是「進程活著但子系統死了」的定案證據。另一個更精準的活性探針是程式的 IPC 回不回真實狀態：正常時查詢會回傳資料、子系統死掉時回空——這比「進程在不在」可靠得多。判「進程活著到底有沒有在運作」時，讀它自己的 log 與 IPC，不是看 pgrep 有沒有輸出。桌面 shell 的具體案例與恢復（讀 caelestia shell -l 抓到 null 根因、重啟重建 scene）見 常見故障場景與恢復操作 的「畫得出來但互動死掉」場景。

服務由誰提供：問註冊表

「某個系統服務現在由哪個程式在提供」，權威來源是服務註冊，不是畫面。桌面服務多半註冊在 D-Bus（Linux 桌面的行程間訊息匯流排）上：一個服務用一個名字掛在上面，而同一個名字同一時間只能被一個行程擁有。以桌面通知為例，org.freedesktop.Notifications 這個 D-Bus 名同一時間只有一個擁有者——兩個通知 daemon（例如 mako 跟某個桌面 shell 內建的通知服務）不能共存，誰先註冊誰佔著，後者只能等前者退出。

想知道現在是誰接管，查註冊表而不是送一則通知看畫面：

1# 查 org.freedesktop.Notifications 目前被哪個連線擁有
2owner=$(busctl --user call org.freedesktop.DBus /org/freedesktop/DBus \
3  org.freedesktop.DBus GetNameOwner s org.freedesktop.Notifications | awk '{print $2}' | tr -d '"')
4# 把那個連線換算成 PID，再看行程名
5pid=$(busctl --user call org.freedesktop.DBus /org/freedesktop/DBus \
6  org.freedesktop.DBus GetConnectionUnixProcessID s "$owner" | awk '{print $2}')
7ps -o comm= -p "$pid"

停掉舊 daemon 前擁有者是舊的、停掉後換成新的，就確認接管成功。這比「送通知看畫面有沒有跳」可靠——畫面沒跳可能是勿擾模式吃掉、可能根本沒送出，畫面反應不等於服務歸屬。切換兩個搶同一服務名的 daemon 時，這也解釋了為什麼「新的裝了卻沒作用」：舊的還佔著名字，新的靜默註冊失敗（通常只在它的 log 留一行 warning），得先停掉舊的。

桌面 session 有沒有被鎖：認清是哪一層的鎖

判斷一個圖形 session 有沒有被鎖，最容易被畫面帶偏，因為「畫面上有密碼框」很有說服力、卻不等於 session 真的被鎖（現代桌面 shell 的儀表板常內嵌鎖屏樣式的 widget）。而且鎖有不同層，查錯層會得到誤導的答案。

關鍵是分清兩種鎖：

• logind 層的鎖：systemd 登入管理的 session 鎖，權威狀態是 loginctl show-session <id> -p LockedHint。
• Wayland 合成器層的鎖：走 ext-session-lock 協議、由合成器（compositor，Wayland 下負責把各視窗合成到螢幕、管輸入輸出的核心程式，約當 X11 時代的視窗管理器加顯示伺服器；Hyprland、Sway 等都是）管的鎖，跟 logind 是獨立機制。這種鎖 loginctl 的 LockedHint 查不到——不是沒鎖，是查錯層。（用 GNOME / KDE 的鎖屏走的機制不同，以下的 ext-session-lock 判法與復原針對 wlroots 系的 Wayland 合成器。）

所以「loginctl 沒有 LockedHint、pgrep 找不到獨立鎖屏程式」不足以斷定「沒鎖」：合成器層的鎖不歸 logind、而鎖屏畫面可能由 shell 主程式在自己行程內畫（沒有獨立可執行檔可抓）。這種情況真正的權威來源是那個 shell 自己的 log（有沒有載入鎖屏模組、idle 計時器有沒有觸發鎖定），或直接看 compositor 的 session-lock 狀態。判鎖看合成器 / shell 的 log，不是 loginctl、更不是畫面有沒有密碼框。

鎖屏程式死掉造成的死局與復原

ext-session-lock 有一個安全設計：持鎖的鎖屏程式若在鎖定狀態下崩潰 / 被中止，compositor 會保持鎖定、不會因為鎖屏程式沒了就解鎖（否則殺掉鎖屏程式就成了繞過鎖的漏洞）。表現是畫面卡在「鎖屏程式已死」的安全提示。復原要從另一個 VT 或 SSH 用 hyprctl keyword misc:allow_session_lock_restore 1 允許新鎖屏 client 接管、再 hyprctl dispatch exec hyprlock 起一個接管後輸密碼解鎖。完整機制、兩層鎖的關係、各 compositor 的差異，見 Wayland Session Lock 卡。

診斷紀律：測鎖屏、或 pkill 一個持鎖的鎖屏程式時，要預期它把 session 卡在鎖定——這是協議的安全設計，不是 bug。 自動化 / 無人值守流程尤其要避免在持鎖狀態下殺鎖屏程式。

終端機多工器的 session 還在不在

用 zellij / tmux 這類多工器跑遠端長任務時，判斷「重連後那個 session 還在不在」的權威來源是多工器自己的 session 列表，不是「我 SSH 斷了所以應該還在吧」的假設。zellij ls（或 tmux ls）會列出 session 與狀態：多工器是常駐在遠端的程序，SSH 斷不影響它，所以只要那台機器沒重開，attach 就能接回去；但如果機器重開過、或那個 session 因為資源不足（例如磁碟滿觸發的連鎖）被殺，列表會顯示它已 EXITED / 不存在，這種接不回去。

這裡有個順序上的紀律：當一個 session 可能已經死掉、而它裡面跑的任務有你在意的產出時，先確認產出有沒有被安全保存，再處理 session。 例如任務是在改 git repo，先 git -C <repo> status 跟 git log @{u}..（本地有、遠端沒有的 commit）確認有沒有沒推送的東西、把該推的推掉，再去 zellij delete 清死 session。搞反順序、先清了 session，可能連帶失去唯一還記得那些改動的地方。權威狀態（git 的推送狀態、多工器的 session 列表）先讀清楚，再動手。

判讀路由

• 判程式活著 → pgrep -x <正確 comm> / pgrep -af <pattern>，先確認實際 comm 名，別用猜的名字。
• 判進程活著但「有沒有在運作」→ 讀程式自己的 log（可能要用它專屬的 log 指令、不在 journalctl）+ 它的 IPC 回不回真實狀態，不是看 pgrep 有輸出就當正常。
• 判服務歸誰 → busctl 查 D-Bus name 擁有者 → 換算 PID → comm，不看畫面反應。
• 判 session 鎖沒鎖 → 分清 logind 層（loginctl LockedHint）vs 合成器層（ext-session-lock，看 compositor / shell log），不看畫面有沒有密碼框。
• 鎖屏程式死掉卡住 → allow_session_lock_restore + 重起鎖屏程式接管解鎖。
• 判多工器 session 存活 → zellij ls / tmux ls；可能已死且有在意的產出時，先確認產出已保存 / 已推送再清 session。

判不準時，診斷心法 的四步（描述症狀、定位權威來源、用對工具讀、矛盾時信權威）是通用的回退。

工作有兩個獨立維度：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 觸發」的具體機制。

寫到「該 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 順序的常見錯誤。

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

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 該做的工作 = 假裝有保護、實際比沒保護更危險。

#86 三層階梯 的「先 L1、不夠升 L2、再不夠升 L3」協議、最容易失敗的點是「不夠」沒量化：

• 沒指標 → 永遠覺得「再觀察一下」 → #72 結構性跳過
• 指標模糊 → 哪天該升、哪天不該、無共識
• 指標太鬆 → 永遠不升、L1 一直撐到崩
• 指標太嚴 → 一個小波動就升、過度工程

正確設計：L1 ship 時就同步定 L2 升級的 trigger 條件 — 閾值、觀測窗口、決策週期、誰負責決策。不是 ship 後再想。

為什麼「再觀察一下」永遠不會升級

「ship L1 → 看效果 → 不夠就升 L2」這個 plan 在沒量化時、實際發生的是：

1. L1 ship、everyone 開心
2. 偶爾有 user 抱怨、但「不知道是不是夠多」
3. 沒有明確 baseline、無法判斷「不夠」
4. 「再觀察一下」變固定回應
5. 半年過去、L2 沒 ship
6. 同類 capability gap 在第 N 個 feature 又發生
7. 「我們系統設計就這樣」變新 baseline

這是 #72 高 ROI 無外部觸發 的具體 case — 升級是 L4（外部觸發）需要的工作、靠紀律失敗。

升級 trigger 的四元素

完整的升級 trigger 含四個元素：

1. Metric（量什麼）

具體可量化的數字、不是模糊「使用者體驗」：

Metric 必須：

• 數值化（有單位、有 baseline）
• 自動量測（不靠 manual 收集）
• 跟 capability gap 直接相關（不是 proxy 的 proxy）

2. Threshold（什麼程度算「不夠」）

明確閾值、寫進 plan：

1Trigger：當 search empty result 率 > 15% 持續 2 週、升級 L2（C1 fallback）
2Trigger：當 L2 ship 後 fallback 觸發率 > 30%、升級 L3（B1 build-time tokenize）

閾值不是猜的、要 justify：

• 從 baseline 推（現況 X、目標 Y、threshold = 中間某點）
• 從業務 SLA 推（acceptable miss rate）
• 從成本曲線推（升級成本 = 維持成本）

3. Window（觀察多久）

避免「一個 spike 就升」、也避免「永遠等」：

Window 太短 = noise 主導、太長 = 真問題拖太久。

4. Decision cadence（誰、何時、how 決策）

「達到 threshold」不該是「自動升級」、是「自動觸發 review」：

關鍵：決策動作有人擁有、有頻率、不靠「想到再看」。

L1 ship 時就定 trigger 的範本

寫 L1 plan 時、同時寫：

 1# L1 (ship now)
 2strategy: UX hint
 3goal: close 50%+ capability gap
 4metric: search empty-result rate
 5baseline: 18% (measured pre-ship)
 6target: < 12% within 4 weeks
 7review: weekly
 8
 9# L2 trigger (defined now, executes later)
10trigger_metric: empty-result rate
11trigger_threshold: > 15% for 2 consecutive weeks AFTER L1 ship
12trigger_owner: search team
13trigger_action: implement client-side substring fallback (C1)
14trigger_eta: within 1 sprint of trigger firing
15
16# L3 trigger (defined now, executes later)
17trigger_metric: fallback hit rate (after L2 ship)
18trigger_threshold: > 30% sustained for 4 weeks
19trigger_owner: search team
20trigger_action: implement build-time suffix tokens (B1)
21trigger_eta: within 2 sprints of trigger firing

ship L1 時、L2 / L3 已經有「上膛」的 trigger — 不靠紀律、靠機制。

反模式

何時不需要量化 trigger

五類共通：量化的成本 > 量化的收益。其他情境必量。

跟其他抽象層原則的關係

套用到當前 search planning case

D + C1 ship 時、應同步定：

 1# D + C1 (ship together)
 2strategy: L1 UX hint + L2 title-only substring fallback
 3metric: search empty-result rate, fallback hit rate
 4baseline: TBD (instrument at ship time)
 5
 6# B1 trigger (defined now)
 7trigger_metric: fallback hit rate (C1)
 8trigger_threshold: > 30% sustained for 4 weeks
 9       OR full-content fallback request from user (manual signal)
10trigger_owner: 你（個人 blog 沒 team）
11trigger_action: 實作 Hugo template suffix tokens (B1)
12trigger_review_cadence: 每月 review search analytics
13
14# 降級 trigger（補強 #86）
15degrade_metric: B1 maintenance cost / build pipeline complexity
16degrade_signal: 升級 Pagefind / Hugo 時 B1 broken 第 N 次
17degrade_action: revisit 是否該換 search engine（換工具 vs 維 transformation）

Pre-ship 把 trigger 寫好 = ship L1 時 L2 / L3 都「上膛」。下次 review 看數據、自動知道該不該升。

判讀徵兆

核心：升級 trigger 的設計跟 ship plan 同步寫、不是 ship 後才想。沒 trigger = 不會升級 = capability gap 永遠在 L1 撐住。「再觀察一下」是缺 trigger 的訊號、不是「我謹慎」的訊號。

背景：我們怎麼管理版本和工作項目

我們的專案用 semver（語意化版本）管理發布節奏。每個版本（如 v0.3.0）有明確的功能範圍，由數個提案定義——每個提案描述一組要交付的功能和邊界。版本內部再拆成多個工作項目（ticket），按批次排序執行（類似 Sprint，但以依賴順序而非時間框分批）。

版本的生命週期很單純：planned → active → completed。一個版本的所有 ticket 完成後，跑發布流程、打 tag、標記 completed。

圍繞這個流程，我們自建了兩個 CLI 工具：

這兩個工具在設計時，都選擇了「彈性優先」——接受任何合法輸入，不對使用者的選擇做判斷。

這個選擇在後來被證明是錯的。

版本語意：大版本和小版本的分工

semver 的 MAJOR.MINOR.PATCH 有明確的語意分工：

版本號不只是標記——它決定了工作項目應該放在哪裡。一個 bug fix 放進 MINOR 版本，語意上等於說「這個 bug fix 和下一批新功能綁定發布」——多數情況下這不是你想要的。

版本管理只是其中一個場景——任何接受自由輸入的內部工具，只要輸入涉及分類或歸屬判斷，都可能有同樣的問題。我們的工具沒有表達這個語意，接下來的兩個事件是後果。

事件一：改善類工作放進了新功能版本

v0.3.0 發布了三個新功能。發布後的版本檢討發現了一個測試隔離問題，v0.3.1 做了 hotfix。

接下來要做根因分析和系統性防護。建立工作項目時，順手指定了 --version 0.4.0——v0.3.0 和 v0.3.1 都已發布，v0.4.0 是下一個功能版本，看起來是合理的選擇。

CLI 接受了這個輸入，沒有任何提示。

三張改善類的工作項目（根因分析、重構、規則文件）就這樣和 PostgreSQL Storage Backend（v0.4.0 的核心功能）混在一起。直到使用者檢視版本看板時才發現不對——改善類工作和新功能綁在同一個發布週期，語意混亂。

修正方式：建立 v0.3.2、遷移三張 ticket、重新發布。額外花了一輪操作成本。

事件二：已完成版本的幽靈

版本看板的異常不止一處。同一次檢視中，看板顯示 v0.2.0 有未完成任務。

查證後發現 v0.2.0（38 張 ticket 全部完成）、v0.2.1（7 張全完成）、v0.2.2（1 張已結案）三個版本在版本清單中仍標記為 active。它們在數個月前就該標為 completed，但沒有。

原因是版本發布工具的 pre-flight 檢查只看「當前版本的 ticket 是否完成」，不掃描「更早的版本是否有 active 殘留」。早期版本可能是手動發布的，跳過了狀態同步步驟。工具沒有補救機制，殘留就一直留著。

看板靜默地把這些版本顯示為「有未完成工作」，產生誤導。

為什麼會這樣：工具沒有 opinion

兩個事件的共通根因：工具在應該有立場的地方選擇了沉默。

建立工作項目時

ticket create --version 0.4.0 --type ANA --action "分析" — 工具知道這是一張分析類的 ticket，也知道 v0.4.0 的 scope 是 PostgreSQL Storage。但它不認為自己有責任判斷「分析類 ticket 放在新功能版本是否合理」。它只做格式驗證：版本號存在嗎？通過就建立。

發布版本時

發布工具的盲區更隱蔽。每次發布時，工具會檢查「這個版本的所有工作項目都完成了嗎？」——如果答案是「是」，就繼續打 tag、更新文件、推送。但它從不回頭看更早的版本：有沒有哪個舊版本的工作項目早已全部完成，卻一直沒被標記為「已完成」？這種殘留不影響當前發布，但會讓看板持續顯示「舊版本有未完成工作」，誤導每一個後續查看看板的人。

兩者都是「工具做了它被要求做的事，但沒做它應該做的事」。

工具什麼時候應該有 opinion？

不是所有情境都需要工具有立場。有一個簡單的判斷標準：

當存在一個「多數情況下正確的預設行為」時，工具應該把它表達出來。使用者可以覆蓋，但預設路徑應該引導正確做法。

這裡的 opinion 是建議而非阻擋——工具提示預設路徑，使用者可以覆蓋。這個區分很重要：阻擋式的 opinion（必須額外操作才能繞過）適合風險高的操作（如 force push to main、刪除生產資料）；建議式的 opinion 適合歸屬判斷。錯誤成本不對稱決定了形式：建議錯了，使用者覆蓋一次，幾秒鐘；沉默錯了，事後修正，幾小時。只要建議的正確率不是極低，建議就比沉默划算。

這個邏輯不限於 CLI。API 的預設參數、表單的預選值、自動化流程的預設路由——任何使用者需要做選擇的介面，都有機會用預設行為表達 opinion。

改善類 ticket 放 patch 版本，在多數情況下是正確的。「多數情況下對」已經足夠讓工具表達立場：

1$ ticket create --type IMP --action "修復" --target "retry test"
2[建議] 此 ticket 為修復類，建議放 v0.3.2（patch bump）
3       而非 v0.4.0（下一個功能版本）
4       使用 --version 覆蓋此建議

前版本 status 掃描也是。已完成版本仍為 active 在所有情況下都是異常——工具不需要猜，只需要報告：

1$ version-release check
2[WARN] v0.2.0：38 張 ticket 全部完成但 status 仍為 active

為什麼使用者是 AI agent 時問題更嚴重

這個 pattern 在人類使用者身上已經存在——人類也會走阻力最小的路徑。但人類有跨次記憶：「上次放錯版本被糾正過，這次注意一下。」

AI agent 沒有這個。

每個 session 是一個全新的 agent，它讀到的是：版本清單中 v0.4.0 是 active、CLI 接受 --version 0.4.0、沒有警告。於是它每次都會用最直覺的選擇——當前 active 的最大版本。

上次的教訓不會自動傳遞到下次。除非教訓被固化成工具行為。

這把「工具應該有 opinion」從「建議做法」升級為「必要條件」：

• 人類使用者：opinion 是提醒，有助於減少錯誤
• AI agent 使用者：opinion 是最可靠的防線，因為工具在操作當下的即時引導是離決策點最近的攔截

工具的預設行為，就是團隊的實際流程

工具的預設行為，就是團隊的實際流程。

文件上寫「改善類工作放 patch 版本」沒有用——如果工具不引導，使用者會走工具預設的路徑。人類和 AI 都是。文件說的和工具做的不一致時，工具會贏。

但文件不是敵人。文件定義「應該是什麼樣」，傳遞設計理由和架構決策；工具實現「實際是什麼樣」。兩者不一致時，優先修工具。

如果你希望使用者做 X，不要寫文件說「請做 X」——把工具的預設行為設成 X。

這個原則適用於所有內部工具設計，不限於版本管理：

每一個「寫文件提醒使用者遵守操作規範」都是一個信號——工具的預設行為還有空間改善。看到這個信號時，優先評估能否把提醒轉化為工具的預設行為。

Rails 的「Convention over Configuration」是同一個觀念的先驅表達：框架用約定引導開發者走正確路徑，省去不必要的配置決策。有 opinion 的工具在必要決策時引導方向。兩者共通的是把判斷成本從「每次使用時」前移到「設計工具時」——一次判斷，永久生效。

回去檢查你的工具

1. 列出你的工具中所有使用者需要做選擇的地方——CLI 參數、API 欄位、表單選項、流程分支
2. 對每個問：有沒有「多數情況下正確」的預設值或建議值？
3. 有的話，加建議式 opinion（提示預設 + 允許覆蓋）
4. 檢查工具的清理路徑：有沒有前一次操作應該同步但沒有同步的狀態？
5. 如果你的工具會被 AI agent 或自動化流程呼叫，上述每一項的優先級加倍——自動化沒有判斷力，它只走預設路徑

57 個 unit test 全綠，但沒有任何機制能回答「這些測試覆蓋了哪些 UseCase 場景」。

monitor 專案 v0.1.0 從需求文件系統（Proposal → Spec → UseCase）一路走到 Collector 實作，中間經過 BDD 測試設計、紅燈測試撰寫、骨架實作讓綠。流程表面上順暢——10 個根 Ticket 全部完成、Collector 可啟動、所有 unit test 通過。但回頭檢視發現：需求→測試的銜接是單向管道，沒有反向追溯，也沒有邊界回補流程。

本文記錄 v0.1.0 的完整流程、發現的五個結構性差異、和落地的解決方案。

實際走過的流程

1saas 選型訪談
2  → Proposal（MVP 範圍界定）
3    → Spec（14 份，涵蓋 schema/ingestion/query/storage/rule-engine/SDK）
4      → UseCase（5 個，UC-01 端到端事件流 ~ UC-05 Web 監控）
5        → BDD 測試設計 ANA（全專案 26 個行為場景 → 整合/單元/協議測試清單）
6          → 紅燈測試（9 個 Ticket 並行，72 個測試 FAIL）
7            → 骨架實作（1 個 Ticket，57 個 unit test GREEN）

每個箭頭都有對應的框架機制：saas→doc 有 Stage 6 銜接、doc→TDD 有 doc-handoff 映射表。但箭頭只往右——沒有任何箭頭往左。

五個結構性差異

差異 1：「全專案 BDD 設計」不在 TDD Phase 模型中

TDD Skill 定義 Phase 0→1→2→3→4 的逐功能流程。v0.1.0 做的是「全專案 UseCase 一次性展開為 BDD 測試設計」，跨越 Phase 1 和 Phase 2 的邊界，粒度是專案級不是功能級。

這不是 Phase 設計的錯——Phase 模型適合增量開發（每次加一個功能）。新專案起手是不同的工作模式：批量設計、模組群組粒度。

解法：在 doc-handoff 新增「新專案起手模式」章節，描述批量 BDD 設計流程、Phase 0 豁免條件、模組群組粒度。

差異 2：紅燈測試需要存根（stub）

Go 是靜態語言，go test 必須編譯通過才能執行。紅燈測試引用的 type/interface 不存在時直接編譯失敗，不是「測試 FAIL」。

TDD Skill 的 Phase 2 說「設計測試」、Phase 3b 說「讓測試綠」，但中間的「建存根讓測試可紅」沒有定義。

實作驗證：v0.1.0 的每個紅燈 Ticket 都自帶建立存根（空 function return nil / 空 struct / 回 501 的 HTTP handler），存根讓 go test 編譯通過，合法測試 PASS、非法測試 FAIL = 紅燈狀態。

解法：Phase 3 rules 新增「存根策略」章節，涵蓋靜態語言（Go/Dart）和動態語言（Python/JS）的不同處理。

差異 3：測試→UseCase 沒有反向追溯

寫完 57 個 unit test 後，問「UC-01 的替代場景 01a（批次部分失敗 → 207）被哪些測試覆蓋？」——沒有任何機制能回答。

doc test-map UC-01 工具存在但回傳 0 個測試——因為它搜尋 UC frontmatter 的 ticket_refs，和測試檔案沒有連結。Spec 的「三方交叉比對」是建 Ticket 時的一次性動作，不是持續追溯。

解法：建立 docs/traceability.yaml 追溯矩陣，三層追溯（UC 場景 → 整合測試 IT-* → 單元測試 UT-* → Spec FR）。每個 entry 標記 covered / gap / deferred。

差異 4：邊界條件發現後沒有回補 UC 的流程

寫 Ingest Handler 測試時發現：「如果 POST body 不是 JSON 怎麼辦？」「如果 Content-Type 是 text/plain（sendBeacon）怎麼辦？」這些邊界在 UC-01 的場景描述中不存在。

測試設計的 BDD ANA 有涵蓋這些邊界場景，但 UC 文件本身沒有更新。邊界條件「住」在測試設計文件而非 UseCase——下次有人讀 UC 不會知道這些邊界存在。

解法：追溯矩陣增加 boundaries: 區段，測試撰寫者發現新邊界時加 gap entry，PM 建 DOC Ticket 回補 UC/Spec。Phase 4d 掃描所有 gap 確認無遺漏。

差異 5：Ticket 拆分邊界未對齊測試變綠驗收點

Collector 實作被拆為 4 個 Ticket：骨架（interface 定義）/ Storage / Ingestion Handler / Query Handler。骨架 Ticket 指派做「main.go + Config + Storage interface」，代理人完成了所有模組實作——57 個 unit test 從紅全部變綠，其餘 3 個 Ticket 的 acceptance 全被涵蓋。

初看像是「代理人超額完成」，回頭用判讀三問檢查骨架 Ticket：完成後有測試變綠嗎？→ 沒有（只定義 interface）。能獨立跑測試嗎？→ 不能（其他模組引用骨架的 type）。共用 type？→ 是。三問全部指向「不應獨立拆」。根因是 Ticket 拆分設計，不是代理人行為——按 Spec FR 拆（輸入驅動）導致骨架 Ticket 完成後 0 個測試狀態改變，不是有意義的驗收點。

判讀規則：實作 Ticket 的拆分邊界必須對齊「測試從紅變綠」的驗收點。一個 Ticket 完成後若沒有任何測試狀態改變，它不應該是獨立 Ticket。

判讀三問：

1. 這個 Ticket 完成後，有測試從 FAIL 變 PASS 嗎？
2. 拆出的各部分能獨立跑測試嗎？
3. 不同部分共用同一組 type/error/constant 嗎？

反模式：按 Spec FR 拆（輸入驅動）。正確做法：按「哪組測試變綠」拆（輸出驅動）。

追溯矩陣的設計

追溯矩陣是三個問題（向上追溯 + 覆蓋驗證 + 邊界回補）的統一解法。

結構

 1UC-01:
 2  title: 端到端事件流
 3  scenarios:
 4    main:
 5      integration_tests: [IT-01-01]
 6      unit_tests: [UT-COL-01-01, UT-COL-02-01, UT-COL-04-01]
 7      spec_frs: [SPEC-002-FR-01, SPEC-003-FR-01]
 8      status: covered
 9    alt-01a:
10      integration_tests: [IT-01-02]
11      unit_tests: [UT-COL-01-03, UT-COL-02-03]
12      spec_frs: [SPEC-002-FR-02]
13      status: covered
14
15boundaries:
16  batch-limit:
17    discovered_during: "ingestion-handler-red-tests"
18    status: gap  # 需回補 UC/Spec

三個問題的對應

整合點

附帶發現：並行派發的 Git 隔離問題

5 個代理人以 worktree 並行派發時，commit 內容交叉混入——A 代理人的 commit 包含 B 代理人的檔案。根因：主 repo 不在 main 分支，多個 worktree 共用同一分支 ref，git add + commit race condition。

防護：派發前確保主 repo 在 main + 已 push。單一代理人和正確條件下的多代理人都驗證通過。

結論

v0.1.0 的流程不是失敗——Collector 可用、57 個 test GREEN。問題在於「走到終點後沒有辦法回頭驗證起點」。需求→測試的管道是單向的：Proposal 說了什麼、Spec 定了什麼 FR、UC 描述了什麼場景，和最終的測試之間沒有結構化連結。

追溯矩陣不增加任何程式碼——它是一個 YAML 檔案，記錄「每個測試為什麼存在」。維護成本是每次寫測試多填一行映射。回報是：任何時候都能回答「這個 UC 場景有沒有被測試保護」。