Readability Review — 四步工作流詳解
本檔為
SKILL.md引用的詳細工作流指南。在每次 review 開始前讀一次。 判準的真實來源是 vault 根 writing-conventions.md；本檔只說明怎麼戴人設把它跑出來。
前置條件
進入 review 前確認：
- 有實際文章可讀 —— 檔案路徑或貼上的全文，缺一不可。憑口頭轉述不能審。
- 是散文文件 —— 設計文件、比對報告、技術文章、spec 概述等。純表格／純程式碼檔不是本 skill 的對象。
不符合任一條 → 明說缺什麼、停下。
步驟 1 —— 取得文章 ＋ 框定人設邊界
目標：拿到要審的全文，並先講清楚這次審查戴的人設邊界在哪 —— 哪些算缺陷、哪些超出人設不報。
取得文章
優先序：
- 檔案路徑（最佳）—— 用 Read 讀全文，能看到完整結構與節標題。
- 使用者貼全文 —— 可用，但若文章很長、節標題不清，先請使用者補一下這篇的用途與預設讀者。
取不到 → 「我需要看到實際文章才能審」，停下。
框定人設邊界
讀全文前，先對使用者對齊這次的人設邊界，避免事後爭論「這條根本不該報」：
我這次戴的讀者人設：產品設計師 —— 不會寫程式，但讀得懂技術文章。
意思是：
- 我會報的：沒鋪路的術語、段落接不上、找不到能反對的地方
- 我不會報的：需要寫程式才懂的內容（那超出人設）、typo／排版
這篇的預設讀者跟用途，跟這個人設吻合嗎？要不要調整邊界？
異常
- 文章其實是要給工程師看的內部實作文件 → 提醒使用者：本 skill 的人設是非工程師讀者，若目標讀者是工程師，審查結果可能過嚴。問是否仍要用此人設。
- 文章極短（幾句話） → 「這篇短到不太需要正式審查報告，我直接口頭給兩三點就好，還是仍要落檔？」
步驟 2 —— 戴人設通讀
目標：以讀者身分從頭讀到尾，把每一次卡頓按閱讀順序記下來。
操作
-
從第一段開始，模擬讀者第一次讀的狀態 —— 不要用「作者視角」（你已知全文）去回填理解。
-
每遇到一次卡頓，當場記一筆，歸到三類之一：
類別 偵測訊號（命中即記） 🚧 卡關點 讀到這裡不知道在講什麼／接不上前一段／「它」「這個」指代不清／一句話塞 ≥2 個獨立命題／結論還沒出現就先丟細節 🔇 插不上話 有取捨或主張，但沒給可指認的錨點／選項沒並排／結論藏在大綱沒在分析節給出／讀者想反對卻找不到入口 📖 術語裸詞 出現一個沒解釋的縮寫／英文裸詞／技術前提，且補一句白話就能讓人設讀懂（見步驟說明的分界判準） -
每筆發現都要具體到能看，記滿三格（缺 before／after 不算完成）：
- 錨點：節標題、第幾段。
- 現狀（before）：直接從原文引出有問題的那句／那段。沒有引文、只有「整體有點難讀」的不寫進報告。
- 修正預覽（after，示意）：給一個改寫示意，讓作者看到方向長什麼樣 —— 不是抽象的「斷句」「補白話」，而是真的把改好的樣子寫出來。這只是示意，不去改原檔，作者自行定稿。
為什麼一定要 after：抽象方向（「拆三段」）等於「用抽象名詞描述方案」，作者得自己腦補成品才知道你在說什麼。給看得見的示意，討論才有實物可對。 📖 的 after 通常是「在原句旁補一句極短 gloss」，不必重寫整句。
「需要 coding 知識」vs「寫作沒鋪路」的分界
這是 📖 與「不報」的分水嶺。對每個技術卡點問一次：
「把這段的前提補一句白話，人設（讀得懂技術文章的非工程師）就讀得懂嗎？」
- 能 → 是寫作沒鋪路，報 📖（或 🚧）。
- 不能（本來就要寫程式才懂） → 超出人設，不報。
例：
- 「走 ACL 防火層 + shadow 並跑」未解釋 ACL 是什麼 → 補一句「ACL＝隔離新舊系統的轉接層」人設就懂 → 報 📖。
- 「
computeIfAbsent的 lambda 在這裡會重入 ConcurrentHashMap」→ 要懂 Java 並發才讀得懂，補白話也難 → 超出人設，不報。
對齊
通讀完先呈現這批（卡關點 ＋ 術語裸詞 ＋ 兩軸初步總評），等使用者回應再進步驟 3：
通讀完了。先給按閱讀順序的卡頓，跟兩軸的初步判斷：
兩軸初判
- 通順：⚠️ 中段有兩處接不上
- 可討論：✅ 大致找得到插話的地方
🚧 卡關點 / 📖 術語裸詞（按出現順序，每筆帶引文＋預覽）
1. 📖 §1 第二段
現狀：> 「經多個轉接器（ACL）餵下游模組。」
卡在哪：「轉接器／ACL」首次出現沒交代是什麼。
修正預覽：> 「經多個轉接器（ACL，隔離新舊模型的轉換層）餵下游模組。」
2. 🚧 §3 第一段
現狀：> 「它在收到工單後先做容量檢查……」
卡在哪：「它」回指上一段哪個主詞不清。
修正預覽：> 「排程引擎收到工單後，先做容量檢查……」
這批看完了嗎？接著我對照文件級判準（架構 A～E）再過一遍。
步驟 3 —— 對照 writing-conventions.md 文件級判準
目標：通讀是「讀者實際撞到的牆」，本步是「拿規範化判準系統性掃一遍」，補上讀者當下未必說得出口、但確實影響可讀／可討論的結構問題。
逐條過 writing-conventions.md「文件級架構」的架構 A～E：
| 判準 | 問句 | 命中時歸類 |
|---|---|---|
| A 雙層（白話上層 ＋ 精確深究層） | 每節有沒有先一段白話框出「這節在答什麼、答案是什麼」，還是直接丟表格／§碼／I/O？ | 🚧（讀者進不來） |
| B 大綱不搶結論，分析節結論先行 | 導讀／大綱有沒有搶著逐項下結論？真正的分析節有沒有把答案放段首？ | 🔇（結論藏起來，難討論）或 🚧 |
| C 標題要有資訊 | 標題能不能讓人從標題就知道底下是什麼？還是「最該先看的 3 件事」這種無資訊標題？ | 🚧 |
| D 中性專業，不對讀者喊話 | 有沒有「你會看到」「先看懂這份在比什麼」這類教學語氣？ | 🚧（語氣，輕） |
| E 把分歧攤平、給可指認的錨點 | 有取捨或爭議處，選項有沒有並排、各帶編號或錨點？讀者有沒有插話的入口？ | 🔇 |
也順帶留意 writing-conventions.md anti-pattern 中直接傷可讀性的項（#1 壓縮密語、#2 後設資料前置），命中就記 🚧。但不要把本步變成 anti-pattern 全項 lint —— 那是寫作自檢清單的事；本 skill 只報「讀者會卡」的那些。
對齊
對照文件級判準補了幾點：
🔇 插不上話（結構層）
- 架構 B：§4 的結論其實在 §0 大綱就先講完了，分析節反而沒再給，讀者要跳回去對 —— 影響討論。
- 架構 E：§5 列了三個方案但沒編號、沒並排，想討論某一個沒法指。
接下來我把兩批合併組裝成報告寫檔，OK 嗎？
步驟 4 —— 組裝報告並寫檔
目標：把所有發現組裝成標準 markdown，寫進 report/。
操作
- 套
output-template.md組裝完整報告。 - 寫到
report/{article}-readreview-{YYYY-MM-DD}.md- article：被審文章的檔名（去副檔名）。範例：
cross-repo-rule-seam-design - 日期：今日
- 範例：
report/cross-repo-rule-seam-design-readreview-2026-06-17.md - 同一篇一天內多審 → 加序號：
...-readreview-2026-06-17-2.md
- article：被審文章的檔名（去副檔名）。範例：
- 報告開頭就是兩軸總評（通順／可討論各一個判斷 ＋ 一句根據），讓使用者一眼看到結論。
- 提示使用者：每個發現都帶錨點，可拿著回去自己揉；要逐段協作改寫再另外開。
收尾話術
審查報告整理好了：
兩軸總評
- 通順：⚠️（中段兩處接不上、一個術語裸詞）
- 可討論：⚠️（兩處結論藏在大綱、一組方案沒給錨點）
發現：🚧 ×3、🔇 ×2、📖 ×1，每筆都帶段落錨點。
我會寫到 report/{article}-readreview-2026-06-17.md，你可以拿著錨點回去揉。
要直接寫檔嗎？
異常情境
文章很長、發現很多
按閱讀順序分批呈現，不要一次倒一份大清單：
這篇較長，卡頓點不少。我建議分段給：
A. §0～§3 的卡頓
B. §4～§7 的卡頓
C. 文件級結構問題
先看哪一批？還是照順序走？
使用者要你「順便幫我改」
報告裡每筆已含修正預覽（after 示意），所以多數時候使用者要的「改好的樣子」已經看得到了。若他要的是「直接改進原檔、整篇順過」：
報告裡每筆都附了修正預覽，你可以直接拿那個示意當起點改。
但「改原檔、整篇接管順過」是另一件事 —— 那我會開 /humanizer-zh-tw 來做（它整篇重寫）。
本 skill 的 after 停在報告裡的示意，不動你的原檔，因為源頭文件你自己揉是這裡的慣例。
要我先把這份報告（含每筆預覽）寫完，還是直接轉去 /humanizer-zh-tw 改檔？
使用者要你評論內容好不好
這超出可讀性審查 —— 我只看「讀者讀不讀得進來、能不能討論」，
不評論「這個設計／主張本身對不對」（那是內容審稿，另一回事）。
不過我可以幫的是：如果某個主張讓讀者「無法判斷該同意或反對」，
那算 🔇 插不上話，我會報。要我繼續嗎？