Tarragon

"原則"

• 2026-04-26 Feature 操作要跟 Source 同層合成 Filter / sort / count / transform / search 是 stream 操作、必須跟 stream 的 materialization 同層或更上游合成。在下游做 = 操作 subset 不是 stream。本原則跨前端 UI、後端 API、演算法管線通用、不只是視覺層 vs 資料層。
• 2026-04-26 寫作便利度跟意圖對齊反相關 寫程式時最容易寫出的版本、通常是離意圖最遠的版本。便利度建立在「現有上下文 / 已 materialize 資料 / 已存在 API」上、而意圖對齊需要找到正確的層、處理上游、跨抽象層 — 兩者方向相反。識別這個反相關 = 識別自己掉進「容易寫的陷阱」。
• 2026-04-26 驗收的時間軸：四個 checkpoint 驗收不是單一動作、是分散在四個時點（寫之前 / 開發中 / ship 前 / ship 後）的累積判斷。每個 checkpoint 能 catch 不同類型的失敗、成本不同。早期 checkpoint 抓越多、晚期 checkpoint 越輕鬆。實務上常常 collapse 成「寫的時候 + ship 後出問題才修」、跳過寫之前 / ship 前。
• 2026-04-26 Test-First：先看到 RED 才相信 GREEN 一個只看過 GREEN 的測試是「未驗證的訊號」、不是「會抓回歸的測試」。必須先在「該失敗的版本」上看到 RED、再在「該通過的版本」上看到 GREEN — 兩次跑都對、才能相信測試真的 catch 到該 catch 的東西。跳過 RED 等於把驗收標準降到「跑得通」、漏掉「測試自己有沒有 bug」這層。
• 2026-04-26 URL 是 stateful UI 的儲存層 — 哪些 state 該寫進 URL 互動式 UI 的 state 散落在多層（in-memory / URL / localStorage / server / index）、每層有不同特性。可分享 / 可恢復 / 可導航的 state 該寫進 URL — 不寫進 = silent 把這些特性犧牲掉。本文展開「state 的儲存層選擇」協議與 URL 的具體位置。
• 2026-04-26 Tab Order = DOM Order = Mental Model 三者對齊 Tab 順序由 DOM 順序決定（除非用 tabindex 強制覆寫）。三者該對齊：DOM 順序、tab 順序、使用者 mental model 的互動順序。三者不一致時、優先重排 DOM 而非用 tabindex — tabindex > 0 是反模式（[#52]）。
• 2026-04-26 高 ROI 無外部觸發的工作會被結構性跳過 工作有兩個獨立維度：ROI 高低 + 是否有外部觸發。高 ROI + 無觸發 = ROI 的承諾、拖延的現實。靠紀律不可行 — 結構性偏差需要結構性對策（外部觸發 / CI / hook / 排程 / pair）。本卡是 #67 便利反相關、#68 checkpoint 跳過、#69 RED 跳過的共同上位原則。
• 2026-04-26 主策略 + 補強策略：選擇不必互斥 多策略並非「五選一」、可分層疊加：root-cause fix（解結構問題） + UX 補強（解使用者感知）通常雙打比單選更穩。判準三條：解不同層 / 沒副作用衝突 / 增量成本可接受。把「策略選擇」預設成單選、會放掉互補可能、產生「結構修了但使用者體驗仍差」或「UX 蓋過去但結構還壞」。
• 2026-04-26 分批 ship：低風險可見價值先行、結構性下輪 「一次 ship 全部」的衝動 vs 「分批 ship」的設計：判準三軸（使用者可見性 / 風險暴露面 / 驗證需求）。低風險 + 高可見 = 立刻 ship；高風險 + 需驗證 = 下輪。對抗「完整才完整」的全做衝動、避免一次塞太多 review surface 拖延上線。
• 2026-04-26 決策對話的五個維度：保持完整選擇空間 對話中的「決策」不是單一動作、是多維度選擇空間：呈現格式 / 策略疊加 / 批次邊界 / 時間軸 / 選項類型。預設多半 collapse 到最窄格（開放問 + 單策略 + 一次完成 + 立刻決 + 單選）、塞使用者進最少自由度的盒子。本卡是 #74-#78 的上層串連 — 五張卡各對應一個維度的鬆綁。
• 2026-04-26 卡片系統的迭代浮現：原子卡 → meta-卡 → reference 三層展開 知識卡片系統不是一次寫成、是 dialogue → 原子卡 → meta-卡 → reference 的迭代浮現。每一輪迭代解決上一輪的 over-fit / under-fit、串連分散的卡片、抽出 meta-原則、最後沉澱成可直接套用的 reference 文件。本卡是 cards-skills 系統設計的 process-level 元原則。
• 2026-04-26 字面攔截 vs 行為精煉：驗證手段跟錯誤層次的對齊 驗證手段必須跟錯誤層次對齊：字面錯誤（typo / syntax / 缺欄位）用 hook / lint / CI 攔截；行為錯誤（思考偏差 / 判斷錯位 / collapse 反模式）用 multi-pass spiral 收斂。強行用 hook 蓋行為錯誤 = 給出 false confidence、反而比沒保護危險。本卡是 #72 結構性對策在「驗證粒度」維度的 ceiling — 不是所有錯誤都該被攔截。
• 2026-04-26 Methodology 的 multi-pass 該升級為 pillar 層：核心結構才會被執行 任何「教做事方法」的 methodology / SKILL / playbook、應該把 multi-pass refinement 放在 pillar / 核心原則層、不是放在末尾「附帶提醒」段。Pillar 層 = 結構性必跑、appendix 層 = 看心情選擇 = 永遠不跑。本卡是 #82 行為驗證 + #72 結構性對策在「方法論設計本身」這一層的展現。
• 2026-04-26 Capability gap 的對策三層階梯：expectation → augment → rebuild 系統有 capability gap（功能不滿足使用者預期）時、對策有三層階梯：L1 expectation alignment（UX hint、訊息精準）、L2 augmenting computation（補一層計算 close gap）、L3 structural rebuild（換 index / engine / 演算法）。三層成本、覆蓋率、脆弱度遞增、不必每次跳到 L3。本卡是 #75 主+補強策略的「不疊加、選層級」變種、跟 #59 五策略矩陣可疊加使用。
• 2026-04-26 Build-time 預處理 vs Runtime 計算的光譜：何時把成本前置 計算可放 build-time（預處理一次、runtime 0）或 runtime（per query 算）— 兩極之間有 hybrid 段（hot path 預算、cold path runtime）。判準四軸：query 頻率 / dataset 大小 / freshness 需求 / build pipeline 複雜度。Build-time 不是「永遠較好」、freshness / 多樣性高時 runtime 反而對。本卡把 #59 五策略中「query-side pushdown vs client-side fallback」的取捨抽象化、跨領域適用。
• 2026-04-26 Dataset 規模改變什麼可行：「需要 index」依 scale 而定 工程師習慣以「production scale」為預設、自動假設「O(N) scan 不可行、需要 index」。但小 dataset 內、O(N) 甚至 O(N²) 都 trivial、不該過度工程。本卡列具體 threshold（< 1MB / < 10MB / < 100MB / > 1GB）對應的可行操作、跟「猜測 production scale 過度設計」的反模式對照。本卡是 #43 最小必要範圍在「規模假設」維度的展現。
• 2026-04-26 升級 trigger 的量化設計：「不夠就升 Y」需要明確的「不夠」指標 「先做 L1、不夠時升 L2、再不夠升 L3」這個分批 ship 順序看似合理、但「不夠」沒量化就會 #72 結構性跳過 — 永遠覺得「再觀察一下」、永遠不升級。本卡定升級 trigger 的量化設計：閾值、觀測窗口、決策週期、自動 vs 人工觸發。預設是寫 L1 ship 時就同步定 L2 升級的 trigger 條件、不是 ship 後才想。
• 2026-04-28 視覺手段對齊錯誤層次：CSS / emoji 修不到語意 / 邏輯問題 修視覺問題的工具（CSS、emoji、顏色、排版）只能擋視覺層、不能修語意 / 邏輯層。把語意 / 邏輯問題當成視覺問題修 = 蓋住症狀根因不動 + false confidence、跟 #82 用 hook 蓋行為錯誤同骨。三層優先序：邏輯 → 語意 → 視覺、修法從深層往淺層走、不從症狀往回推。本卡是 #82 在「呈現層」的具體實例、是 #83 multi-pass review 缺的 vertical 軸。
• 2026-04-28 URL slug 必須顯式定義為 fact：跨工具 identifier 用單一定義源 URL slug 在 Hugo 預設下從 title 自動推導、在 mdtools lint 下從檔名讀、在跨檔連結時又要寫第三個值 — 一個 identifier 散落在三個推導鏈、典型 SSoT 違反。當多個工具共用一個 identifier、推導不一致 = silent broken link。修法：把 slug 從 derivation（runtime 推導）升級成 fact（frontmatter 顯式定義）、檔名 / 連結都基於這個 fact。本卡是 #44 在 toolchain integration 情境的具體實例、是 #82 字面 vs 行為在 identifier 維度的展現。
• 2026-04-29 正向改寫要保留對照論據、不能空降結論 把「X、不是 Y」改成正向陳述時、若直接刪除「不是 Y」會讓結論失去推理依據、變成空降斷言。對照論據（Y 是讀者直覺會想到的替代方案）跟結論（X）是同一個推理單元、抽掉一半就不成立。正向改寫的合法做法是補解釋、改成對照表、或保留 Y 當對比錨點 — 直接拿掉是 worst。
• 2026-04-29 Multi-pass review 的 scope 要蓋『同類風險區』、不是『改動區』 做 multi-pass review 時、預設用『我這次改過的檔』當 scope 是便利選擇；但同一原則違反通常分布在整個 corpus、改動區只是冰山一角。Scope 該由『同類風險的內容範圍』決定 — 跑某條原則的 pass、就要掃所有適用該原則的檔、不是只掃我自己改過的。改動區 scope 是 #67 在 review 流程的具體展現、會讓 multi-pass 退化成 self-edit pass。
• 2026-04-29 適用範圍要展開成 file enumeration、口語描述不夠 原則的『適用範圍』寫成口語描述（『所有教學文件的論證段落』）時、執行 review 的人要當場推導『具體哪些檔屬於這個範圍』、推導步驟容易漏；改寫成 enumerated file list（具體列出 file paths）就能避免 enumeration 不完整。Enumerate 的合法形式是『可被 grep / find 重現的具體 file 集合』、不是『口語類型描述』。本卡是 #95 的下游具體化、跟 #82 互補：enumerate 是字面層、enumeration completeness 是行為層判準。
• 2026-05-01 資安教學的審查標準要對應風險不對稱 一般教學寫不清楚、讀者學不到、損失停在學習端；資安教學寫不清楚、讀者照做後在系統上產生破口、損失轉嫁到生產端。兩者風險不對稱、審查嚴格度應該對應下游實作代價、不是讀者讀懂程度。資安內容的 audit bar 預設要拉到「讀者會 implement」、不是「讀者會 read」、否則所有寫作便利選擇（含糊敘述、省略邊界、引用而不驗證版本）都會 silent 變成實作端破口。
• 2026-05-01 False sense of security 是資安寫作的主要失敗模式 資安教學內容的失敗模式不是「讀者學不到」、是「讀者以為學到了並照做、實際還有破口」。讀者實作後沒警覺 = 後續驗證、修補、事件偵測都不會被觸發、破口在生產系統長期 silent 累積。識別 false sense of security 句子的判準：讀者讀完後會說「我做了 X 防護所以安全」、卻無法回答「對什麼 threat 安全 / 什麼 deployment 條件 / 什麼前提失效」。
• 2026-05-01 Threat model 明確性：「防什麼」與「不防什麼」必須對稱 資安 mitigation 的論述要對稱寫「防什麼 threat」+「不防什麼 threat」。只寫前者、讀者會自行 universal 詮釋（防所有相關攻擊）、實際只擋作者腦中 subset、是 false sense of security 的主要產地。對稱論述不是讓文章變負面、是讓 mitigation 的 scope qualifier 顯式化、讓讀者能驗證實作覆蓋邊界。
• 2026-05-01 Mitigation 對位：防護對應到具體 threat 的驗證 資安寫作裡 mitigation 寫得乾淨不代表對到 threat、必須讓「mitigation X → 防 threat Y」的對應鏈可被反向驗證。常見失效模式：mitigation 攔的是 threat 的 surface artifact、不是 mechanism；mitigation 跟 threat 在不同抽象層；mitigation 假設 threat 已被上層擋掉但上層沒擋。對位驗證的 audit 模板：每個 mitigation 列出「設計攔的 threat」+「驗證 mechanism」+「失效訊號」三欄、缺一即 false sense of security 產地。
• 2026-05-01 Mitigation 的 context-dependence：deployment 條件改變有效性 同一個資安 mitigation 在不同 deployment / runtime / scale / config 條件下、有效性差異很大、甚至完全失效。寫作時把 mitigation 描述成 universal（「使用 HTTPS 保護傳輸」「JWT 用簽章驗身分」）會跳過 context、讀者實作時用單一條件詮釋、deployment 條件不對時 mitigation silent 失效。每個 mitigation 必須附帶「成立條件」+「失效條件」+「deployment 變數列表」。
• 2026-05-01 Security 標準引用的時效性與精確度 資安 citation 跟一般技術引用不同——best practice 時效短（MD5 / SHA-1 / bcrypt 100k / TLS 1.0 都曾是 best practice）、原文常被引用扭曲（conditional → unconditional drift）、版本不標 reader 會套用過時 spec。citation 同時涵蓋外部標準（OWASP / RFC / NIST / CIS）跟內部 citation（knowledge-cards / 跨章引用作為 control-of-record）；後者因無版本號 anchor 反而更易 silent drift / broken。每條 citation 必須附：版本 / 年份、引用句意可回溯、deprecated / superseded 標記、強度參數對應 actor 能力的 review trigger（外部）/ last-checked + sync owner（內部）。
• 2026-05-01 Audit recommendation 層級：accept / minor / major / 教錯不可保留 資安 audit 的產出不該是「OK / 不 OK」二選、要分層給 ship 決策用：accept（無 weakness）/ minor revise（補 boundary 級小改）/ major revise（結構性 false sense、需重寫）/ withdraw（教錯主動誤導、必須移除或全換）。前三層對應學術 peer review、第四層是資安 audit 特有——當內容會 silent 把 reader 帶向破口時、保留是淨負面、不存在「先 ship 後改」的選項。
• 2026-05-01 用 Next-action frame 取代 Disclaimer：把 prohibition 翻成 actionable chain 當 audit / risk 識別 reader 不該做 X、寫作回應若停在 disclaimer 段（告訴 reader 不要 X）、整段自然產出 negative phrasing（不是 / ≠ / 不要）、即使逐句翻正向句法仍是 disclaimer。Reframe 成 next-action 段（告訴 reader 沿 chain 做 Y / Z）整段自然 positive、不需 contrast。Frame 選擇是 #94 正向改寫的上游問題——逐句正向化處理不到 frame 層、reframe 整段才會根治。
• 2026-05-06 設計檢討用當下三軸論證、不依賴 hindsight 本卡提倡用「當下成本對稱條件下選了限制更高的選項」當設計缺陷的判定方式、避免 hindsight 論述把需求演化誤判成設計缺陷。當下三軸論證（成本對稱性 / 可逆性 / 領域先驗）讓判斷不依賴結局發生、且歸因偏向工具預設與制度而非個人預見性。
• 2026-05-06 口語化修辭在判斷工具型段落會稀釋技術精度 技術文章的「判斷工具型段落」（讀者用來判斷自己 case 的論述）用「一輩子」「碰巧能用」「立刻撞牆」「沒事」這類口語修辭、會稀釋精度。修法是把口語修辭翻譯回技術屬性語言。但 hook / 引言 / narrative 段落用口語仍然合理——這是情境化的取捨、不是精度永遠優於可讀性。
• 2026-05-06 地區用語對齊：寫作前先確定讀者的中文語料 繁中 vs 簡中的用詞差異不只是字形（屏 / 螢幕、視頻 / 影片）、更是技術術語跟業務情境的精度差。寫作前要先確定讀者的中文語料、避免用對方語料中不存在或意思偏移的詞。常見漂移：硬體（屏 / 螢幕）、檔案系統（文件 / 檔案）、概念詞（默認 / 預設）、修辭詞（質量 / 品質）、混雜情境的英文中文比例。
• 2026-05-06 商業邏輯論述要 self-contained：不依賴 code 才能被理解 技術文章在「不放 code 的段落」仍然要 self-contained——商業邏輯論述不能預設讀者已經看過 code、用「那個 payload 第二段」「剛才的變數」這類 reference 等於把理解門檻轉嫁給讀者去翻 code。修法是把 reference 翻譯成「用名詞 / 角色 / 條件描述」的 self-contained 句子、即使讀者跳過所有 code block 也能理解論述。
• 2026-05-06 Multi-pass review 的 frame 顆粒度盲點：抽象規則 → 具體訊號的轉譯不完整 Multi-pass review 跑了 4 輪、字句層問題（口語修辭 / 地區用語 / 依賴 code / 廢話前綴）仍漏 catch——揭露 frame 顆粒度盲點：抽象規則（如「機會成本語氣」「正向陳述」「最重要的話優先說」）沒被轉譯成具體訊號（如 grep keyword bank：「一輩子 / 碰巧 / 撞牆 / 下次 X 時 / 不是 A 而是 B」）。修法是把每條規則展開成可 grep 的 keyword bank、加 reader simulation 輪、加 self-criticism 輪。
• 2026-05-18 Collapse 是隱形預設：多維空間被壓成單格的三類典型 決策對話、決策呈現、批量輸出三個 surface 都有同一個 pattern — 高維選擇空間預設被 collapse 到 1-2 個窄格、且這個 collapse 因為「便利 / 合規 / 簡潔」被當成中性預設、不被覺察；#80 是 decision surface 上的極致 collapse、#79 是 dialogue 五維 collapse、#123 是 output framing 在 constraint 下 collapse；三者共骨：*某個高自由度空間被便利驅動 reduce 到最少格子*；對策不是去除 collapse、是讓 collapse 變顯性、由設計者決定要 collapse 哪一維、不是預設全 collapse
• 2026-05-18 寫作 review 是多軸完整性、不是單軸深度 寫作 review 的完整性不是單一軸越做越深、是多軸交集都對齊；#83 frame 軸 + #121 instance 軸 + #97 surface 軸 + #95 scope 軸 + #122 cadence 軸 + #124 timing 軸 + #114 granularity 軸、七軸正交、缺任一軸都會 systematic miss；review 設計時要 enumerate 七軸覆蓋狀況、不是只跑一兩個維度做深；是 #79 五維決策對話在 review 工具設計的姊妹卡
• 2026-05-19 Process content 結構由最大差異維度決定、不是 universal phased 跨 X process content（migration / upgrade / rollout / playbook）的結構由 source / target 之間 *差異維度組合* 決定、不存在 universal phased 模板；6 種 migration / process type 實證（schema 差 / drop-in / operational / multi-tool / paradigm / topology re-layout）跑出 6 種不同結構；寫作前必須做 *6 維 diff dimension audit* 才能決定結構、跳過會套錯模板
• 2026-05-19 Data topology 是 process content 的第 6 audit 維度 Process content 的 diff dimension audit 原本 5 維（schema / operational / paradigm / components / application change）漏了 *data topology* — 資料在 cluster / partition / region 之間的分佈拓樸；topology 不在既有 5 維任一個、但決定 re-sharding / partition redesign / multi-region rollout 的結構；本卡擴 audit 到 6 維、新增 Type F「Topology re-layout」結構
• 2026-05-20 新增頂層 content 資料夾要同步首頁 _index.md 入口 Hugo 不會 auto-list 頂層資料夾、首頁的模組清單是 content/_index.md 的手動 curated markdown。新增 content/<module>/ 後若沒同步加入口、模組在首頁完全不可發現；讀者只能靠搜尋或直接打 URL 才進得去。本卡把『新增頂層資料夾 + 首頁入口』綁成同 commit 的雙生動作、避免下次再漏。是 #44 SSoT 在『首頁清單』維度 + #97 metadata surface 在『上層索引』維度的具體案例。
• 2026-05-20 WRAP Widen Options 容易塌成稻草人 framing、要改 evidence weight 結構 WRAP 框架的 Widen Options 段在案例寫作中容易塌成「列爛選項 → 打掉 → 留正解」的修辭結構、變成稻草人 setup。問題不在框架本身、在於寫作時把 Widen Options → Reality Test 當作全文 narrative 主軸。修法是把 Widen Options 從「對抗稻草人」改成「並陳合理因果鏈用 evidence 配重」、Reality Test 從 binary verdict 改成 weight assessment + Falsifier。是 #125 Collapse 在 WRAP 寫作 surface 的具體 instance、#79 多軸決策的姊妹卡。
• 2026-05-20 WRAP 是寫作者的內部工具、不是文章章節結構 WRAP 框架（Anchor Check / Step 0 / Widen Options / Reality Test / Attain Distance / Prepare to be Wrong / Tripwire）是寫作者背後做 hypothesis 探索與認知偏誤防護的內部工具。當把這些 process 標籤暴露成文章章節標題、讀者會踩三個壞 effect：預設讀者認知、塞滿 meta dialogue、同論點重複預告。修法是把 WRAP 工作內嵌進教學 narrative、章節順序服從教學流程。是 #140 WRAP Widen Options 稻草人的上位原則、跟 #125 Collapse 同骨。
• 2026-05-20 文章主體要對齊標題承諾、WRAP 內部分析不該喧賓奪主 文章標題對讀者做了承諾、文章主體必須對齊這個承諾。WRAP 內部分析（Widen Options + Reality Test 含 prior 引用 + evidence weight）即使方法論做得好、如果不是標題承諾的內容、就不該佔文章主體—屬於 scope mismatch、跟 process metadata 暴露（#141）的議題分開。附帶議題：當 WRAP 內部分析喧賓奪主、為了支撐 prior 容易引入沒實際出處的 source citation；把 WRAP 內部分析從主體移除、hallucination 風險自然降低。是 #141 的姊妹卡—#141 處理章節標題 surface、本卡處理章節內容 scope。
• 2026-05-20 外部分析文章要先拆成事實、作者判讀、本文推導 把外部分析師文章轉成教學型商業分析時、原文不是可直接搬進正文的 case fact。寫作者要先把材料拆成三層：可驗證事實、原作者判讀、本文推導。三層混寫會讓分析師 frame 被讀者誤當事實、也會讓本文自己的結論失去可回溯性。修法是先做 source layering、再決定哪些內容進事件段、哪些內容只作為 hypothesis prior、哪些內容要標為本文合成。
• 2026-05-20 跨領域分析要先定位讀者層級、再決定術語密度 把商業分析寫給工程背景讀者時、不能繼承原分析文章的 VC / founder / industry insider 讀者假設。跨領域寫作要先定位來源文章與目標讀者的層級差，再決定術語密度、因果鏈步長與例子粒度。若直接沿用高密度商業語言，文章看似專業、但讀者只能記名詞，無法複製判讀。
• 2026-05-20 外部分析改寫的交付物是可遷移框架、不是風格轉換 把其他分析師文章交給 AI 改寫時、任務目標不能停在語氣、段落與措辭符合本站風格。教學型商業分析的交付物是讀者可帶到下一個事件使用的判讀框架。若只做風格轉換，文章會像摘要或二次評論；若做框架轉換，文章會把事件拆成訊號、機制、風險、預警與下一步路由。
• 2026-06-01 字句層 review：keyword bank 命中是候選、不是判決 跑了字句層 grep keyword bank、命中『不是 A 而是 B』、卻把它判成『可接受的反例對照』放行；違規由讀者 catch。揭露 keyword bank 的第二層盲點：偵測（grep 命中）跟判定（這個命中是不是違規）是兩個認知步驟、reviewer 容易把命中合理化成合規而放行。判定準則：否定句構若在『建立核心概念』就改正向、只有在『明示反例段落』才保留。另有一類贅語（訴諸群體『很多人卡在』）連關鍵詞都沒有、keyword bank 結構上抓不到、要靠 reader-simulation 語意 pass。
• 2026-06-01 教材用中性陳述、不對讀者喊話 教材的 register 是中性陳述概念、不是對讀者說話。三種對讀者喊話的形式 —— 安撫情緒（很多人卡在）、第二人稱代入（你天天寫）、祈使控制閱讀（先讀懂 / 別搞混）—— 表面不同、共同違反是把讀者當成要管理的對話對象、而非把概念講清楚。問題不在精度（「你天天寫的 int count」精度完全正確）、在 stance。修法是換成中性陳述（常見的 int count）或描述性名詞標題（簽章的型別與名字拆解）。邊界：hook / narrative 段落的輕度第二人稱可幫讀者進入、不一律禁。
• 2026-06-01 教材給技術理由、不替方案下品質評價 教材該陳述「為什麼這樣設計」，不對方案下品質評價。自評誇飾（教科書級 / 堪稱經典 / 完美契合 / 漂亮地解決）讀起來像作者在誇自己方案、傳遞的是滿意度而非概念，且品質評價會頂替掉真正的技術理由 —— 寫了「X 是教科書級的適配」就少寫了「X 為什麼適配」。修法是把評價換成機制 / 條件。邊界：帶判讀條件的適配性陳述（三條件齊備時 HOF 比列舉更省）是判準、不是誇飾，保留。
• 2026-06-01 教材把設計選擇講成選擇、不講成必然或天性 本質主義 / 必然性框架（天生 / 本質就是 / 必然 / 唯一）把一個設計選擇講成自然法則、抹掉設計能動性，讓讀者以為沒得選。它是『機會成本語氣 vs 絕對主義』違反的一個 subtype —— 不是命令式絕對（應該做 X）、而是必然性絕對（X 本來就這樣）、更隱形。sharp feature 是常局部牴觸作者自己在別處的條件性立場。修法是把必然框架還原成條件性：X 在『選了某前提』之後才以此形式成立。邊界：物理 / 法律 / 合規事實可講必然。
• 2026-06-01 Review 漏抓先分 design gap 與 execution gap、再決定改框架還是改執行 Review 漏抓某類問題時，有兩個不同成因：design gap（框架根本沒有對應 frame）跟 execution gap（框架有 frame、但 reviewer 沒跑）。修法相反 —— design gap 要改框架（補 frame / keyword）、execution gap 要改執行（真的跑完該跑的輪）。診斷前先分清：把 execution gap 誤判成 design gap 會 framework bloat（一直加 frame 卻沒解決偷跑子集）、把 design gap 誤判成 execution gap 會永遠漏同類。常見陷阱是『加 keyword』感覺像進步、但對沒跑的輪毫無幫助。
• 2026-06-05 教材的『重點 / 總結』段是內容發散的訊號、該重組正文不該補丁 教材尾端的『重點』『一句話總結』段、若功能是重述前面已講過的內容、就是正文組織不佳的補丁。讀者需要回頭被提醒、代表概念在正文裡散掉了 —— 該做的是重拆正文段落、把概念在它該出現的位置一次講清、而不是另開總結段替發散的正文善後。判準：刪掉總結段後正文若仍站得住、證明總結本就冗餘；若站不住、是正文要重組、不是總結要補。處理總結段內容時先分『提醒 vs 概念』—— 純提醒（養成習慣 / 回頭確認）刪、有概念價值的（為何這樣設計）併回它本該所屬的正文位置。
• 2026-06-11 引用章節用語意標題、不用位置編號：編號是結構排列的 derivation、會隨版本漂移 跨段落、跨檔引用結構單位（章節 / 階段 / 條列項）時、引用語意標題（副標題）、不引用位置編號（Stage 3、第 5 章、第 3 點）。編號是「目前結構排列」的 derivation、不是 fact；結構重排時編號全部位移、引用點不會報錯、而是 silent 指向錯的內容 — 比 broken link 更難偵測。標題的存在意義就是承載可被引用的語意。是 #44 SSoT 在結構引用維度的實例、#93 identifier-as-fact 家族的 sibling、#84 命名承載語意的引用面延伸。
• 2026-06-11 集合命名用角色、不內嵌數量：「核心七問」的七是成員數的 derivation、加一問就全面失真 「核心七問」「成長六階段」「四大支柱」這類名稱把成員數量烤進名字裡 — 數量是集合當前成員的 derivation、不是集合的語意身分；成員增減時名稱失真、且名稱是被複製最多次的字串、缺陷隨每次引用繁殖。修法：命名只承載角色與層級（核心問題 / 次要問題 / 撞牆階段）、數量讓清單自己呈現。本卡是 #155 的命名端 sibling（#155 修引用端、本卡讓「語意標題是穩定錨」的前提真正成立）、#44 SSoT 在名稱內容的實例、#84 命名檢驗的數量維度。
• 2026-06-11 語意錨用單一字串、同義雙名讓引用修復退回人腦對應 引用錨在語意標題之後、語意名稱本身要是單一字串。同一個結構單位有兩個同義名稱（標題寫「決策記錄 + scaffold 建議」、引用寫「決策收斂階段」）時、語意引用的兩個核心收益同時失效：grep 要掃兩套 pattern 才完整（漏配置一個就漏一半引用點）、重排時的引用修復回到人腦對應。是 #155 引用端、#156 命名端之後的第三塊：命名唯一性。
• 2026-06-11 決策表兩列同時命中且結論相反：缺的是一個上游區分維度 判讀表 / 決策表的兩列規則被同一個真實案例同時命中、且指向相反結論時、問題通常出在表外：案例承載著兩種身分、而表缺少把身分拆開的上游維度 — 修法是補前置澄清問、把維度抬到表之前；拆不出身分的矛盾才是規則真衝突、回表內改規則。偵測方法是用真實案例 dry-run、不是逐列檢查 — 單列都正確的表仍可能整體矛盾。
• 2026-06-11 入口分流要放在詞彙牆之前、門外讀者要在門外就拿到岔路 一個模組為「還沒進門的讀者」補了專屬章節、但模組入口頁的開頭全是門內讀者的詞彙、分流句埋在數十行後 — 目標讀者在抵達分流點之前就跳出了。分流的位置要依「最外圈讀者的存活範圍」決定：他讀得懂的區域有多長、分流就要出現在多早。內容寫得再友善、入口斷路就等於沒寫。
• 2026-06-11 跨 surface 同主題內容要重新語境化、不是搬運：逐字相同句是未語境化的訊號 同一個原則要同時存在於兩個 surface（教材章節與 agent 協議、blog 卡與 skill 卡）時、規範說「各寫一份、語境化在各 surface 內」— 語境化的可操作判準是：句子要跟著該 surface 的讀者與用途改寫、兩邊逐字相同的句子是未語境化的候選訊號、命中後逐處判讀。逐字搬運讓兩份內容形成沒人宣告的隱性同源、改一邊另一邊 silent 漂移、且兩邊都沒有為自己的讀者最佳化。
• 2026-06-11 摘要壓縮可以丟細節、不可以改模態 description、索引 hook、目錄註解這些壓縮層在濃縮規則時、最容易丟失的是約束的模態 — 「可延後、但不可沉默」是帶條件出口的設計、壓成「不可跳過」變成絕對禁令。模態失真比內容遺漏更糟：讀者從壓縮層建立的預期跟本體矛盾、規則的彈性設計（出口、條件、記錄義務）被摘要抹掉。壓縮丟細節是本職、丟模態是失真 — 判準是讀者只依摘要行動、會不會做出本體不要求、或錯過本體允許的事。
• 2026-06-11 引用卡片用被引卡自己的分類詞彙：改寫對方的 taxonomy 是隱性錯引 宣告「本卡是 X 卡在某維度的延伸」時、描述 X 卡的詞彙要用 X 卡自己的分類體系。被引卡把 link label 歸在 navigation surface、引用方寫成「metadata surface 的一種」— 關係精神成立、詞彙錯位：讀者循連結過去、發現被引卡的分類表跟引用句對不上、引用的可信度連帶整張卡的可信度一起折損。引用前重讀被引卡的分類段、用它的詞彙描述它。
• 2026-06-11 多階段流程的 artifact 欄位契約：下游宣稱的輸入要能從上游產出推導、推導規則要明文 多階段流程裡、下游階段宣稱「以上游的 X 為輸入」時、X 需要的每個欄位要嘛直接存在於上游的產出格式、要嘛有明文的推導規則。上游表七欄、下游要求的「失敗語意」欄不在其中也沒有推導說明 — 執行者只能自由心證、每次推得不一樣、漏標的欄位剛好是下游分支的開關。檢查方法是逐欄走查：把下游輸入格式的每一欄、對到上游產出格式的欄或一條明文推導。
• 2026-06-14 register 違規：偵測可機械化、判定要靠文體異源的眼睛 寫作規範的違規分兩類：形式違規（emoji / 編號 / broken link）可完全機械判定、該進工具鏈；register / 品味違規（概念前置 / 否定起手 / 喊話 / 誇飾）的判定有不可消除的品味核心。「不是 X、而是 Y」的陷阱是偵測可機械化（grep 抓得到句型）偽裝成判定可機械化、誘導無限投入更精緻的判定方法（grep → 概念位置 → 行為測試）、但判定始終在品味側、始終放水。更深一層：產出這類違規的 LLM 跟審查它的 LLM 共享文體直覺、同源自審對 register 違規有結構上限、加再多輪次都跨不過。結構解是引入文體異源的視角（人類冷讀 / reader-simulation / 對抗文體 reviewer）、並接受 100% 自動 catch 不可能。
• 2026-06-14 重點優先陳述是跨語言的資訊結構原則、不是中文句型問題 正向陳述優先的本質是資訊結構效率：讀者拿到核心概念的認知步驟越少越好。「不是 X、而是 Y」表達能力差、是因為它讓讀者先處理一個被否定的錯誤理解 X 才拿到正確的 Y、重點後置多繞一步。這個缺陷跨語言成立——英文 not X but Y、日文 X ではなく Y 同樣高頻、換語言不打破（證偽過的反例假設）。判別線是「核心概念在不在最前」、統一了 #94（重點先行合法）與 #149（重點後置違規）、且可操作。LLM 系統性放水的根因是高頻偏置（把語料高頻句型評為表達好、高頻不等於資訊結構優、跨語言）。主解是強制執行重點位置判準、#165 的異源視角降為補充。
• 2026-06-14 修法是新違規的來源、且常引入同類變體 修法（改寫違規句、補 lint 規則、改 pattern）這個動作本身會引入新違規、而且引入的常是同一類問題的變體——修「不是 X、而是 Y」就暴露「不是 X — 是 Y」、補一個 pattern 就漏下一個變體。所以 review 的 scope 要涵蓋修法後的產物、不只原始內容；停止判斷不能停在「修完這批」、因為修法本身產生新一批。同類變體靠判準（重點位置）收斂、不靠窮舉 pattern；補 pattern 永遠追不上變體（打地鼠）。
• 2026-06-18 多輪審查要有冷讀者 frame：知情 reviewer 看不見行話洩漏 多輪審查模擬讀者時要分兩種：知情讀者（讀完全部、走旅程）與冷讀者（經搜尋或直連落在單篇、零脈絡）。知情 reviewer 會自動腦補脈絡，結構性看不見洩漏撰寫者預設前提的行話。原子 / Zettelkasten / glossary 等可被直連抵達的內容，必須額外跑冷讀 frame。
• 2026-06-18 原子筆記要有向上的議題入口：讀者要知道為何讀這張、何時會撞到 承載知識的原子筆記不是字典條目。每張卡（或其上層）要回答「你在討論什麼議題、撞到什麼問題，才需要這個知識」——從情境進入，而非從定義進入。做法是建『議題 hub』上層筆記討論問題、再分流到術語卡，術語卡頂部回指議題。
• 2026-06-29 Description 是未來自己的 recall trigger、不是文章摘要 文章的 description 欄位要讓未來的自己在掃列表時判斷「我現在遇到的問題，該不該回來讀這篇」——像 skill 的 description 讓系統決定何時載入一樣。摘要式 description 只回答「這篇在講什麼」，recall trigger 回答「你在什麼情境下需要這篇」。
• 2026-06-25 列舉與數字殘留在定義型文件會製造維護債務 定義型文件（規則、規格、常駐名單）中的冗餘列舉（A-G）和描述性數字（9 個函式、428 行）是撰寫過程中的推理殘留——作者先算出範圍再寫定義，但最終文件只需要定義本身。列舉讓每次擴充都要回頭更新引用處，數字讓每次重構都要校準計數，兩者都是維護成本但不增加閱讀價值。判斷標準：如果拿掉列舉或數字，讀者理解不受影響 → 刪除。
• 2026-06-26 讀者是缺經驗的專業人士、不是外行人 技術教材的讀者定位應該是「在這個領域缺乏經驗的專業人士」，不是「完全不懂的外行人」。寫法是補足經驗缺口、不是從零科普。宣導式語氣（跑得好好的、你可能不知道）預設讀者無能，實際上會降低教材的可信度。
• 2026-06-26 跨專業溝通用情境遞進、不用比喻堆疊 向非本領域的專業人士解釋技術議題時，減少術語並從簡單情境遞進到複雜情境，比堆疊比喻有效。比喻傳遞形狀但不傳遞嚴重性；情境遞進讓對方用自己熟悉的決策框架（成本、風險、時間）消化資訊。
• 2026-06-26 技術教材要內嵌管理層可彙報的資訊 技術文章的讀者不只要知道怎麼做，還要能向上彙報為什麼做、花多久、花多少。成本量級、時程估算、進度指標與需簽核的決策點應該嵌在技術段落旁邊，而非集中在另一篇溝通指南裡。
• 2026-06-26 多輪審查缺 outside-in 讀者 frame：六個系統性盲點 review 框架的所有 frame 從已寫的內容出發（inside-out），缺從讀者完整需求出發的 frame（outside-in）。六個盲點全部由使用者而非 reviewer 發現：宣導語氣、管理層資訊缺失、接手情境遺漏、工具指引缺失、深度不拆分、讀者定位未預設。
• 2026-06-26 操作指引的「怎麼做」要帶環境專屬的工具路徑 操作型教材說「拍下現況」「匯出資料庫」「建立備份」時，不同執行環境（container / VM / 共享主機）的工具路徑完全不同。只寫動作不寫工具，讀者知道該做什麼但做不到。這個缺口在 fact-check 和 steelman 審查裡結構性隱形，因為動作本身在邏輯層是正確的。
• 2026-06-26 跨 surface 鏡像的連結轉換 mapping 要窮盡、不能靠猜 skill 鏡像從 .claude/skills/ 複製到 content/skills/ 時，references/principles/ 的相對連結要轉成 /report/ 的真實路徑。mapping table 不完整會讓 CI 反覆 broken link，每次修一批漏一批。窮盡 mapping 的方法是列出所有 principle 檔案再逐一找對應 report 卡，不是靠 slug 精確匹配碰運氣。
• 2026-06-26 先建 report 卡再進 skill、不是先改 skill 再補 report report 卡是原則的 SSoT（有情境、根因、理想做法），skill 是 report 的操作化引用。先有 report 才有 skill 引用的依據。反過來做會讓 skill 裡的規則缺乏可追溯的根據，且 report 容易被跳過。
• 2026-06-26 常識是相對於讀者背景的、不是作者背景的 知識卡的建卡判準不能用「這個夠不夠常見」——對 PHP 工程師是常識的 .htaccess，對 Node.js 工程師完全陌生；對後端工程師是常識的 DNS TTL，對前端工程師需要解釋。建卡看的是目標讀者群裡最不熟悉的那個人能不能理解，不是作者自己覺得夠不夠普遍。
• 2026-06-29 一篇文章只承擔一種功能：SOP 跟 retrospective 混寫兩邊都做不好 文章同時塞操作步驟（SOP）和批次驗證紀錄（retrospective）時，機器讀者找不到可執行的步驟、人類讀者不知道哪段是給自己看的。
• 2026-06-29 Log 時間真空是 silent hang 訊號、happy log 是 anti-signal 非互動 process（CI / cron / container init）的最後一行 log 是成功訊息、到被 cancel 之間有大段時間無輸出時回來。判讀靠訊息時序的真空、不是最後一行的成功訊息。
• 2026-06-29 Report 卡的論述基礎記結論和 evidence 來源、不記檢討過程 report 卡的論述基礎與限制段寫「從哪來、evidence 邊界是什麼」，不寫「怎麼發起的、用了什麼工具分析」。過程是作者的工作紀錄、結論才是讀者需要的判讀前提。