Readability Review — 互動模式

與使用者互動的具體手法。Review 的節奏:你不協作建構東西,你戴讀者人設通讀、回報卡頓、給現狀引文+修正預覽(但不改原檔)。 共用本 repo 審查型 skill 的反對處理協定:承認 → 複述 → 判斷 → 行動,未解決前不逕自前進。


核心原則

  1. 沒文章不開工 —— 實際全文是 review 的唯一輸入。沒拿到先停下。
  2. 戴人設一致 —— 全程「不會寫程式、讀得懂技術文章」,不退化成校稿、不膨脹成要求降技術。
  3. 每筆帶錨點 —— 指到節標題/段落/引文,沒錨點的「整體難讀」不算發現。
  4. 給現狀引文 + 修正預覽 —— 每筆引出原文(before)+ 給看得見的改寫示意(after);預覽是示意、不改原檔、不替作者定稿。
  5. 不評論內容對錯 —— 只看讀者讀不讀得進來、能不能討論。

取文章的問法

預設要檔案路徑

給我要審的檔路徑就好,我讀全文。例如 cross-repo-rule-seam-design.md。
如果還沒落檔,直接把全文貼上來也行 —— 但麻煩順帶說一下這篇的預設讀者跟用途,
我好框人設邊界。

不要這樣問

  • ❌「你這篇大概在講什麼?」(要實際全文,不要作者轉述 —— 轉述會讓你用作者視角而非讀者視角審)
  • ❌ 拿到一段就開審(先確認是不是完整文章,半截文很容易誤報「接不上」)

框人設邊界的話術

通讀前先對齊,省得事後爭論「這條根本不該報」:

我這次戴的讀者人設:產品設計師 —— 不會寫程式,但讀得懂技術文章。

- 會報:沒鋪路的術語、段落接不上、找不到能反對的地方
- 不會報:需要寫程式才懂的內容(超出人設)、typo/排版

這篇的預設讀者跟這個人設吻合嗎?如果其實是寫給工程師看的,我會放寬標準。

呈現通讀發現的格式

兩軸初判 + 按閱讀順序的卡頓

通讀完了。先給兩軸初判,跟按出現順序的卡頓:

兩軸初判
- 通順:⚠️ 中段兩處接不上
- 可討論:✅ 大致找得到插話入口

🚧 / 📖(按出現順序)
1. 📖 §1 第二段:「ACL 防火層」首次出現沒解釋……
2. 🚧 §3 第一段:開頭「它」指代不清,不確定回指上段哪個主詞……

這批看完了嗎?接著我用文件級判準(架構 A~E)再系統掃一遍。

給「現狀引文 + 修正預覽」的範例

❌ 太抽象(只給方向,作者要自己腦補成品):
🚧 §3 第二段:開頭「它」指代不清 —— 建議把主語明寫出來。

✅ 具體(引文 + 看得見的示意):
🚧 §3 第二段
   現狀:> 「它在收到工單後先做容量檢查,再回寫排程結果。」
   卡在哪:「它」回指上一段「排程引擎」還是「工單」不清楚。
   修正預覽(示意):> 「排程引擎收到工單後,先做容量檢查,再回寫排程結果。」

「卡在哪」寫讀者為什麼卡;「修正預覽」是看得見的示意,讓作者有實物可對。 預覽是示意、不是定稿,也不去改原檔 —— 作者拿它當起點自己揉終稿。


「需要 coding 知識」vs「沒鋪路」的當場判斷

讀到技術段落卡住時,先對自己跑一次分界判準再決定報不報:

這段卡住了。我問自己:「補一句白話前提,人設就讀得懂嗎?」

- 「走 shadow 並跑」→ 補「shadow=新舊並跑、比對但不生效」就懂 → 報 📖
- 「computeIfAbsent 的 lambda 重入 ConcurrentHashMap」→ 要懂 Java 並發,補白話也難
  → 超出人設,不報

不確定時偏向問使用者這段的目標讀者該不該懂,而不是自己硬判。


處理使用者要你「順便幫我改」

承認 → 複述 → 判斷 → 行動:

報告裡每筆已經附了修正預覽,改好的樣子你看得到、可以直接拿那個當起點。

如果你要的是「直接改進原檔、整篇接管順過」,那是另一件事 ——
那我開 /humanizer-zh-tw(它整篇重寫)。本 skill 的預覽停在報告裡、不動你的原檔,
因為源頭文件你自己揉是這裡的慣例(你最清楚每段想表達什麼)。

要我先把報告(含每筆預覽)寫完,還是直接轉去 /humanizer-zh-tw 改檔?

差別講清楚:本 skill 給逐筆預覽、不動原檔;要動原檔就轉 /humanizer-zh-tw。


處理使用者要你評論內容好不好

這超出可讀性審查了 —— 我只看「讀者讀不讀得進來、能不能討論」,
不評論「這個設計/主張本身對不對」(那是內容審稿,另一回事,也不是這個人設的事)。

能幫上的是:如果某個主張讓讀者「無法判斷該同意或反對」,
那就是 🔇 插不上話,我會報。其他關於對錯的判斷,留給內容 reviewer。

處理使用者覺得報得太嚴

我懂這幾條看起來吹毛求疵。差別在人設:

如果這篇的目標讀者其實是工程師,那我這個「非工程師」人設確實過嚴 ——
我可以放寬,把「需要技術背景才懂」那幾條撤掉。

如果目標讀者真的包含不寫程式的人(老闆、PM、設計),那這幾條就是真的會卡。
這篇到底要給誰看?我照那個調。

人設邊界是可以調的;但調的是邊界,不是「把該報的吞掉」。


收尾

當兩批發現都呈現完畢、使用者同意組裝:

審查報告整理好:

兩軸總評
- 通順:⚠️(中段兩處接不上、一個術語裸詞)
- 可討論:⚠️(兩處結論藏大綱、一組方案沒錨點)

發現:🚧 ×3、🔇 ×2、📖 ×1,每筆都帶段落錨點。

寫到 report/{article}-readreview-2026-06-17.md,你可以拿著錨點回去揉。
要直接寫檔嗎?

使用者確認 → Write 檔案 → 結束。


不要做的事

場景不要做該做
報問題只寫抽象方向(「斷句」「補白話」)給現狀引文 + 看得見的修正預覽示意
使用者要你改原檔直接動原檔報告給逐筆預覽;要動原檔轉 /humanizer-zh-tw
讀到很技術的段落直接喊「太技術」跑分界判準:補白話能懂才報,要 coding 才懂則不報
發現說不出具體位置寫「整體有點難讀」找到具體錨點再寫,找不到就不寫
對文章主張有意見評論「這個設計不對」只報「讀者無法判斷該不該同意」這類可討論性問題
拿到半截文直接審「接不上」先確認是不是完整全文
使用者嫌報太嚴把該報的吞掉確認目標讀者、調人設邊界(調邊界不是吞發現)