論述基礎與限制

這則檢討處理一種常見的說明形態：條列式斷言——「拆開來看有三個毛病：1、2、3」。觸發案例是一篇 work-log 檢討文章的段落，第一版列出一則註解的三個毛病（「入口」是自創行話、「由誰設定」grep 一下就有、「用途」重複型別名稱），而正文只給了那一行註解本身——讀者無從驗證程式裡有沒有「入口」這個識別符，也看不到 grep 會落在哪裡。三條結論都是對的，但讀者只能選擇硬記或盲信。改寫後的版本由提出問題的使用者判定「把原本說明不清楚的東西說得清楚非常多」，並要求固化成寫作模式。

限制兩項：單一案例（一個段落、一次改寫），修法的普遍有效性是機制推導；有效性由提需求者判定，沒有第三方讀者的理解測試。

核心原則

條列式斷言是作者走完推導後只輸出結論。 每一條的背後都有作者做過的動作——搜過識別符、對照過型別宣告——但清單只留下動作的結果。判定這段說明合不合格用重建測試：讀者只憑文中已經給出的材料，能不能自己得出這一條結論。能，清單是合格的壓縮；不能，讀者拿到的是要求信任的裁決，說明的功能沒有發生。

重建測試同時暴露第二個問題：斷言清單會把「缺材料」藏住。 「入口是自創行話」這條斷言成立的證據是實際的進入點程式碼，而那段程式碼在第一版根本不存在於文中——清單的形式讓缺席的材料看起來不缺，因為結論已經寫在那裡了。

修法：讀者位置的走查

三步，把斷言清單展開成讀者能跟著走的過程：

  1. 把讀者放到使用產物的位置。 不是「這則註解有三個毛病」，是「跳到這行、想從註解拿到資訊的讀者，逐字檢查它給了什麼」。位置決定了後面每一步的判定標準——資訊拿不拿得到，而不是作者覺得好不好。
  2. 每條斷言換成動作加材料。 「入口是自創行話」換成：搜 入口、搜 entry，找不到任何識別符；然後給出實際的進入點程式碼，並排對照「寫識別符、搜尋一次落點」與「寫行話、讀者得自己猜」。動作是讀者可以自己做的，材料是文中直接給的，結論由對照自己浮現。
  3. 檢查方式放在走完之後。 「把型別名稱唸出來、doc 還剩什麼資訊」這種可重用的判準，在三步走完後出現時是讀者已經能自己說出的東西；放在清單前面就是又一條要硬記的規則。

走查的副產物是逼出缺的材料：第二步做不下去的地方，就是文中該補而沒補的程式碼、輸出、對照——這正是斷言清單藏住的缺口。

對照範例

改寫前（斷言清單）：

1拆開來看有三個毛病：
21. 「入口」是自創行話，程式裡沒有這個識別符。
32. 「由誰設定」grep 一下就有。
43. 「用途」只是把型別名稱再唸一次。

改寫後（走查、節錄第一條）：

1「由進入該模式的入口設定」——「入口」指什麼？在程式裡搜「入口」、搜
2entry，找不到任何識別符。實際的進入點是兩個按鈕的 handler：〔程式碼〕
3對照這段程式碼就看得出落差：註解若寫「由 enterBatchMode 的呼叫端設定」，
4讀者搜這個識別符、一次就落在這兩行；寫「入口」，這個詞只存在於註解裡。

第一條裡的問句是操作型自問——它是讀者要執行的動作、答案由緊接的材料交付，跟懸念型問句（答案被扣住）不同類。

審查掛載

多輪審查的斷言支撐 frame 對每個結論式條列跑重建測試。曝光候選的 grep 訊號：

1rg "拆開來看|[一二三四五六]個毛病|有[一二三四五六]個問題"

命中是候選不是判決，判定靠重建測試本身。兩類合規要放行：每條自帶證據的清單（引用的材料就在文中）；摘要位置的清單（文末收斂、前文已推導過——走查已經發生，條列是回收不是灌輸）。

跟其他抽象層原則的關係

  • #254 教學與檢討內容寫給帶問題來的讀者：同根因（結論與推導脫節）的段落層形態。#254 管篇章層的敘事姿態——懸念把結論扣在推導後太遠、灌輸把結論放在推導前沒有支撐；本卡把灌輸那一半落到段落層並給出修法範式（走查）。兩卡出自同一篇文章的連續兩輪修訂：先修姿態、再修論證單位。
  • #242 形態讓讀者對號入座，微案例才讓他想像得出後果：同屬「給材料讓讀者自行完成認知動作」家族。#242 給的是敘事材料（微案例讓後果可想像）、本卡給的是驗證材料（程式碼與對照讓結論可重建）；兩者的反面同構——純分類與純斷言都是只有結論的形式。
  • #244 範例讓最後一類出口缺口現形：同一個機制的另一面。#244 講補範例這個動作讓「讀者下一步去哪」的缺口現形，本卡的走查讓「支撐這條結論的材料」的缺口現形——兩者都是換到讀者的動作視角後、原本不可見的缺席變得具體。
  • #262 內容超出容器時擴充結構、不壓縮內容：本卡的重建測試是 #262「條列連綴」形態的判定工具（條列的每條、讀者能不能自己得出）；本卡的走查修法正是 #262「就地展開」出口的具體作法——把塞進條列與表格的推導攤回正文。

判讀徵兆

徵兆該做的行動
「拆開來看有 N 個」「三個毛病」式的條列引導逐條跑重建測試：讀者用文中材料能不能自己得出這條
條列裡的結論引用了文中沒有出現的對象（程式、設定、輸出）缺的材料就是該補的：給出那段對象、讓對照自己說話
可重用的判準出現在條列之前移到走查之後，讓它浮現而不是被宣告
審查回報「這段說明不清楚、讀者可能無法理解」用走查三步改寫：讀者位置、動作加材料、結論後置
文末摘要的條列被判成違規檢查前文有沒有推導過——推導過的條列是回收，合規

適用範圍與邊界

  • 適用：教學與檢討內容裡承擔說明責任的條列——讀者被期待理解並同意每一條。
  • 邊界：
    • 摘要與收斂位置的條列：前文已走過推導，條列是壓縮回收，合規。
    • 每條自帶證據的清單：條目直接引用文中已給的材料，重建測試本來就過。
    • 規格與參考型內容：API 參數表、設定項清單——它們是查閱對象不是論證，重建測試不適用。