WRAP 詳細技巧說明
WRAP 詳細技巧說明
本文件提供 WRAP 每個階段的詳細操作技巧、範例和判斷規則。 四個階段各自對付一個決策 villain（狹隘框架、確認偏誤、短期情緒、過度自信），階段為什麼這樣切、對應關係與《Decisive》的來源見 references/principles/four-villains.md。
0. 錨點確認 — 詳細操作
任務認領時的錨點確認
每個任務認領後、分析/派發前，確認核心目的：
| 問題對 | 選項 A | 選項 B |
|---|---|---|
| 交付策略 | 快速交付（最小修改） | 穩定架構（花時間做對） |
| 問題性質 | 找 Bug（根因 + 最小修復） | 系統設計改善（系統性重構） |
| 優先維度 | 使用者 UX 體驗 | 執行效能 |
這是權重排序問題：在這個任務的脈絡下，哪個權重更高？
開發途中的重新確認
觸發重新確認的時機：
- 資源耗盡時 → 「簡化 scope 快速交付，還是維持完整度？」
- 發現額外問題時 → 「一起處理還是建任務延後？」
- 方案需大幅修改時 → 「核心目的有沒有改變？」
第三錨點：評估單位
嚴重性先取決於評的是什麼對象。同一個發現當成一個實例評是校對問題，當成一種形態評、全集合量出幾十處，是規範問題——兩個評級都對，對的是不同的對象。逐篇審查的單位是一篇，每篇各自結案「一處、輕微」，模式從不被組裝，所以模式層的嚴重性對逐篇審查結構上不可見。
操作：給嚴重性之前寫下評估單位；形態層先量普及度（可 grep 的跑全集合計數，不可的抽樣冷讀）再評級；逐篇審查對可能是模式的發現只標候選，嚴重性由聚合步驟給。兩個評估者分歧時，先問兩邊評的是不是同一個對象。三個反模式：從修復成本推嚴重性（量的是作者側）、新發現直接歸進最接近的既有類別繼承其嚴重性（歸類快於量測是訊號）、評估者自動補完後回報「讀得懂」（審查者做的正是讀者做的事，盲區重合）。這一格在 Step 0 之前，因為對象沒定就擴增選項，擴的是錯的問題。詳見 /report/evaluation-unit-before-severity/。
Step 0 — 資料充足度閘門詳細操作
為什麼 Step 0 必須在 W 之前（完整版）
W 階段「擴增選項」擴增的是選項空間，但選項的意義取決於當事人條件。如果不先確認資料充足度：
| 表面現象 | 實際狀況 |
|---|---|
| 列出 A/B/C/D 四個選項（看似多元） | 四個選項都基於「用戶是平均值」的假設 |
| 對選項做現實檢驗（Reality Test） | 只是驗證「對平均值用戶是否可行」，非「對此用戶可行」 |
| Attain Distance 考量機會成本 | 比較的是錯誤假設下的成本 |
| Prepare to be Wrong | 預想的失敗原因都是技術性，忽略「假設錯誤」這個最大風險 |
結論：Step 0 缺失會讓整個 WRAP 流程變成「精美的錯誤分析」。
反模式偵測（完整版）
| 警告信號 | 含義 |
|---|---|
| 擴增選項（Widen Options）時寫出「適合的用戶選 A，其他用戶選 B」 | 已承認用戶差異會影響選擇，卻未先確認用戶是哪種 |
| 選項描述含「通常」「一般來說」「大多數人」 | 用群體敘述替代個體判定 |
| 執行現實檢驗（Reality Test）時發現「資料來源是群體統計」 | 這屬於 Step 0 應提前檢出的問題 |
| Attain Distance 的機會成本計算需假設用戶偏好 | 偏好是 Step 0 資料，不該在 A 階段假設 |
各專案可建立個人化建議的三層機制（識別 / 分級 / 誠實）。
W — 擴增選項詳細技巧
爬梯子法範例
以「掛鉤（Hook）錯誤處理」類的除錯場景為例：
| 層級 | 搜尋 | 結果 |
|---|---|---|
| 0. 身邊 | 當前專案既有模組（例如追蹤器/派發器） | 已有 API 但沒接線 |
| 1. 同層 | 同類元件的清理機制 | 類似功能的掛鉤（Hook）已有方案 |
| 2. 同領域 | 官方 GitHub Issues | 多個 Issues 報告同樣症狀 |
| 3. 跨領域 | 其他 extension host 錯誤處理 | 類比：宿主不應被擴充崩潰 |
教訓：早一輪往上爬，比在原地換寫法便宜。在「身邊」層反覆試 3 輪的成本，通常高於第一輪就跳到「同領域」層去搜尋 — 後者往往 10 分鐘就有答案。
向外求解（Find Someone Who’s Solved Your Problem）
核心問句：「還有誰跟我一樣在為這個問題傷腦筋？我可以從他們那裡學到什麼？」
做法：
- GitHub Issues 搜尋：
{工具名} {症狀關鍵字} - Stack Overflow / 官方文件搜尋
- 如果找到 → 可能根本不需要自己實作
AI 內建知識調用
AI 擁有兩種「爬梯子」工具：
| 工具 | 適用場景 | 範例 |
|---|---|---|
| 內建知識 | 經典解法、設計模式 | 「CLI 掛鉤（Hook）系統的常見錯誤處理模式？」 |
| 網路搜尋（WebSearch） | 最新進展、特定版本 | 「Claude Code hooks 2026 hook error」 |
擴增選項三步走：
- 自問內建知識 → 產出 3-5 個已知方案
- 網路搜尋（WebSearch）驗證 → 確認是否過時、發現新解法
- 當前專案適配 → 選擇適合當前架構的方案
假選項偵測規則（季辛吉陷阱）
季辛吉回憶錄：國務院給尼克森三選項（核戰/現狀/投降），實際只有「現狀」可選。
| 檢查 | 問題 | 不通過信號 |
|---|---|---|
| 根因多元性 | 選項基於不同根因假設？ | 全指向同一根因 |
| 途徑多元性 | 選項代表不同解決途徑？ | 全是同一途徑的參數微調 |
| 利害關係人 | 只考慮一方觀點？ | 沒有「不做」或「問別人」的選項 |
| 框架測試 | 能一句話概括所有選項？ | 可以 → 框架太窄 |
範例案例：改 exit code / 改 stderr / 改 stdout → 本質都是「修改掛鉤（Hook）」→ 假選項。
二元處置取捨：完整論證與實證
SKILL.md 保留判斷標準的核心定義、邊界與 Action；本節收錄完整 Why/Consequence 論證與兩則實證。
Why：處置類問題（「這個東西該留還是該拿掉」）天然以對立軸呈現，設計選型類問題（「該選哪種形態」）天然以有限選項呈現，兩者直覺產生的選項清單都會被單一程度軸或既有框架限定，而真正的解常在該軸之外（移位、換執行點、重新定義對象）。選項一旦列出即封閉解空間，且該封閉對決策者不可見——決策者只會看到自己列了三個選項，不會看到沒被列出的第四個。
Consequence：使用者只能在被限定的清單內選擇，或必須自己看穿框架才能提出第四個選項。決策品質上限由列選項者的框架決定，而非由問題本身決定；設計選型類若跳過此檢查，額外風險是「推薦」的方案可能只是基於未查證的基本率假設，被後續現實檢驗推翻時已耗費使用者一輪決策成本。
升級條件的理由：處置對象涉及防護能力增減（移除守衛、降級閘門、停用檢查）或不可逆變更時，W 階段不足，須跑完整模式。理由是這類處置的錯誤代價不對稱——R 階段的基本率與既有機制查證常會推翻 W 階段看似完整的選項集，而 A 階段的悖論檢查是「守衛是否誠實」這類問題的唯一結構化把關。
實證（處置類）：某次面對「hook 出口被降級後該保留還是回退」的處置決策，直覺清單為三項（保留 / 回退 / 先複核）。跑 WRAP 後，W 階段反向框架把問題從「出口該多硬」重寫為「這個防護該不該存在於此執行點」，方案擴增至 5 項，使用者最終採用的方案不在直覺清單內。
實證（設計選型類）：某次面對「文件索引寫入的接線方式該選哪種形態」的設計選型決策，直覺列出三個選項，選項間在「無旁路強度」與「自動寫入版控檔的副作用風險」兩軸上代價方向相反（強度高者風險也高），且能被一句話概括（三選項皆為「接線層級」的程度差異），未通過框架概括測試；首輪標為推薦的方案且基於未查證的基本率假設，被現實檢驗（Reality Test）證偽。
R — 現實檢驗詳細技巧
問對問題：基本率問法
向 AI 問基本率（過去和現在），不問預測（未來）：
- 「類似案子的重要變數是什麼？」
- 「多少比率在 X 階段就解決？」
- 「成功的案例有什麼共同特徵？」
AI 本質上是基本率的巨大資料庫 — 擅長回答「通常怎麼解決」而非「這次會不會成功」。
大範圍觀照（Zoom Out）+ 近距離檢視（Zoom In）操作
大範圍觀照（Zoom Out）：
- 搜尋社群基本率：「多少人遇到同樣問題？」
- AI 內建知識：「這類問題通常怎麼解決？」
- 統計性判斷：「做了這決定，合理預期會發生什麼？」
近距離檢視（Zoom In）：
- 讀具體案例內文（不只 Issue 標題）
- 讀 source code（不只代理人報告，實際 git diff）
- 小規模實驗驗證假設
如同羅斯福的訊息策略：不完全依賴單一來源，多源交叉驗證。
試水溫操作範例
| 場景 | 全力投入（錯誤） | 試水溫（正確） |
|---|---|---|
| hook error | 直接改核心函式 | 先手動測試一個 hook 的 exit code |
| 語意重命名 | 一次派發改 5 個檔案 | 先改 1 個檔案確認消費端不壞 |
| 新功能設計 | 完整實作後才測試 | 先寫最小概念驗證（POC）驗證核心假設 |
試水溫成本：5 分鐘。全力投入失敗成本：2 次修改 + 1 次回退 + 問題惡化。
最強版本論證流程
來源：努金調解索尼 vs 蘋果 — 「我會陳述對方的立場，且優於其自我陳述。」
操作步驟：
- 列出被放棄選項的優點（比其支持者說的更完整）
- 列出選定方案的缺點（至少 3 個）
- 自問：「我能否闡明反對意見，且優於反對者自己的陳述？」
- 能 → 真的理解了取捨（trade-off）
- 說明不足 → 可能還在確認偏誤中 → 回到 R 階段
A — 拉開距離詳細技巧
機會成本顯性化範例
除錯情境範例：
1選項 A：修改核心錯誤處理函式
2 機會成本：花 2 小時可能白做，這段時間可以推進其他任務
3 風險：根因判斷錯誤 → 改壞更多元件
4 不選其他的代價：沒有搜尋社群，可能 10 分鐘就有答案
5
6選項 B：搜尋 GitHub Issues
7 機會成本：10 分鐘
8 風險：找不到相關 Issue
9 不選其他的代價：如果是自己的 bug 就需要回來修工具選擇檢查（Tool selection check）詳細技巧
問題背景：LLM 在選工具（tool）時有結構性偏誤：單步決策敏感、總步驟數盲點。會把「3 步繞路」誤估為「1 步直達」，因為每個單步看起來都合理。物化工具（tool）名稱（「用 Write」）會進一步鎖死思考框架。
觸發條件：
- 選工具（tool）前（選擇具體工具呼叫的那個瞬間）
- 預估步驟數 > 2（有 2 個以上 tool call 才完成目的）
- 涉及 Write/Bash 組合（尤其 Write 到中介檔再讀回再寫入的模式）
4 問操作流程：
| 問題 | 自我質疑 | 回答「是」的行動 |
|---|---|---|
| Q1 物化檢查 | 我描述任務時用的是工具（tool）名稱（「用 Write 建 ctx 檔」），還是目的語言（「把 context 寫進任務紀錄欄位」）? | 重寫任務描述為目的語言，再重選工具（tool） |
| Q2 步驟數檢查 | 列出實際 tool call 序列，數一下是幾步? 有無「1 步路徑」（單一 tool call 直接完成）被忽略? | 換成 1 步路徑（heredoc / Edit 直接改 md） |
| Q3 目的地檢查 | 產出的最終目的地是哪裡?（CLI stdout / 檔案系統 / 任務紀錄 / log）工具選擇是否匹配目的地? | 目的地若是任務紀錄 → 首選 Edit；若是 append CLI → 首選 heredoc Bash |
| Q4 白名單檢查 | 我選的 tool 是否在「低摩擦首選」名單外? 有無不必要引入中介檔? | 換成白名單內工具 |
「低摩擦首選」白名單（長文寫入類）：
| 目的地 | 首選工具（tool） | 次選 | 避免 |
|---|---|---|---|
| 寫入任務紀錄欄位 | Edit（直接編輯紀錄） | task append + heredoc | Write 暫存檔 → Read → Bash |
| 執行 CLI 含長參數 | heredoc $(cat <<'EOF'...EOF) | 單引號整段 | Write → Bash 讀入 |
| 寫 commit message | heredoc | 多行 -m | Write 中介檔 |
情境反向驗證
原場景（繞路）：決策者要把 1.5KB context 寫入任務紀錄的 Solution 欄位，選擇：
Write /tmp/ctx.md建暫存檔Read /tmp/ctx.md讀回Bash: task append --file /tmp/ctx.md
4 問驗證：
| 問題 | 原場景答案 | 結論 |
|---|---|---|
| Q1 物化 | 「用 Write 建 ctx 檔」(物化) vs「把 context 寫進任務紀錄」(目的) | 觸發 → 重寫為目的語言 |
| Q2 步驟數 | 3 步（Write / Read / Bash） vs 1 步（heredoc Bash 或 Edit 任務紀錄） | 觸發 → 有 1 步路徑被忽略 |
| Q3 目的地 | 目的地是任務紀錄的 Solution 欄位；/tmp 中介檔非必要 | 觸發 → 應首選 Edit |
| Q4 白名單 | Write 到 /tmp 屬白名單外繞路 | 觸發 → 換 heredoc 或 Edit |
正確路徑（1 步直達）：
1task append TASK-ID --section "Solution" "$(cat <<'EOF'
2（content here）
3EOF
4)"或更直接：Edit 工具打開任務紀錄編輯 Solution 欄位（0 步 tool call，整合在 Edit 單次呼叫內）。
教訓：4 問任一觸發，都是「繞路訊號」——單步都合理不代表總路徑短。
核心優先事項排序
典型軟體專案的優先事項（由高到低）僅供參考，各專案應建立自己的排序：
- 產品功能開發
- 程式碼品質
- 開發流程改善
- 工具維護
衝突時用排序終結爭論：第 4 項 vs 第 1 項 → 第 1 項勝 → 工具維護建任務延後。
P — 準備好犯錯詳細技巧
行前預想操作
Gary Klein 方法：先假設計畫失敗了，然後問「是什麼殺了它？」
- 比問「可能會失敗嗎？」多產出 25% 的洞察（且更具體）
除錯情境的行前預想範例（如果當時做了）：
- 失敗原因 1：根因判斷錯誤（可能性 > 50%）→ 已超過閾值，不應執行
- 失敗原因 2：影響範圍不清（可能性 40%）
- 失敗原因 3：實際執行環境行為不如預期（可能性 60%）
安全係數參考
| 領域 | 安全倍數 |
|---|---|
| 電梯鋼纜 | x11 |
| 太空梭地面設施 | x4 |
| 微軟軟體專案 | +30% 時間 |
| 代理人任務派發 | 預估時間 x 1.5 |
展現謙卑：我們容易過度自信，所以預留緩衝。
Last Updated: 2026-09-08 Version: 1.3.0 — SKILL.md 收斂至 5,000 tokens 門檻下：新增「Step 0 — 資料充足度閘門詳細操作」章節（為什麼必須在 W 之前完整版、反模式偵測完整版），新增「二元處置取捨：完整論證與實證」子節（W 階段）；SKILL.md 對應段落壓縮為核心定義 + 路由，完整 Why/Consequence/實證移入本檔 Version: 1.2.0 — A 階段新增工具選擇檢查（Tool selection check）4 問 + 情境反向驗證