| name | requirement-protocol |
| description | 從需求確認到實作的對話協議：模糊指令澄清（含篩選類）、可決定 vs 該確認的邊界、失敗 2 次的轉折、覆寫成本告知、revert/checkpoint 處理、漸進驗證、工具切換時機。Triggers: 收到模糊指令, 自決還是確認, 反覆失敗, 換思路, 覆寫成本, 先還原, 先重來, placeholder, 最小範圍, 推理失敗, playwright 切換, 開發前澄清, 需求確認, 排除障礙, 逼近答案, 依 X 篩選, 只看 X, filter 範圍, 呈現決策, 開放問, ABCDE 你選哪個, 反省題, retrospective, 下一步往哪走, 五維度, 需要我繼續嗎, 要做嗎, OK 嗎, yes/no, 二選, 確認嗎. |
| license | MIT |
| metadata | {"version":"0.1.0","category":"collaboration-protocol"} |
Requirement Protocol
從需求確認到實作的對話協議。把「使用者下指令 → 執行者實作」之間的溝通流程結構化、避免反覆失敗、避免做出使用者沒要的東西、避免在錯誤方向上累積沉沒成本。
協議的核心命題：對話成本與重做風險之間有最佳化空間。全自決對話成本最低、但容易做錯；全確認重做風險最低、但對話爆炸。協議定的是「哪些該攤、哪些自決」、以及「卡住時該怎麼轉彎」。
Core Pillars（四大支柱）
| 支柱 | 意義 |
|---|
| Visibility-Based Confirmation 可見性確認 | 使用者會看到的決定（數字 / 順序 / 文字）攤開確認、純技術細節自決 |
| Two-Occurrence Threshold 2 次門檻 | 第 1 次是運氣、第 2 次是訊號；同方向失敗 2 次就停、不沿同方向加碼到 3 |
| Cost Transparency 成本透明 | 覆寫深度、revert 影響、最小必要範圍 — 把成本攤開讓使用者參與決策 |
| Multi-pass Refinement 多輪精煉 | 第 1 輪實作不追求完美、預期會有未發現問題；設計第 2 / 3 輪用不同 frame 收斂、不是「再仔細一次」、是換角度看（#82 / #85） |
Seven Principles（七大原則速查）
讀者在本區塊能完成大方向判斷；具體情境的展開（步驟 / 模板 / 反例）依下方「觸發路由」進對應 reference。
1. 可決定 vs 該確認的邊界
純技術實作（grid / flex、ResizeObserver / setInterval、selector 寫法）可自決；使用者會看到的決定（breakpoint、預設尺寸、filter 順序、UI 文字、配色）先列選項給使用者點頭。
判準三問：UI 上會不會產生使用者感知的差異？選不同會不會影響體驗？寫進 commit 後改動成本高不高？ 任一個「是」 → 該確認。確認時給「選項 + 推薦 + 開放修改」、不要開放問。
2. 同方向失敗 2 次 = 停下驗證假設
第 1 次失敗多半是執行細節（typo、cache、syntax）— 修了再試。第 2 次同方向失敗、不要再試一次更小心、用工具驗證底層假設（DOM tree、computed style、framework 行為）。
驗證後分兩條路：假設對 → 繼續修；假設錯 → 換方向、不為前面的努力買單。第 3 次同方向加碼（更複雜的 selector、加 !important、再寫一層 polyfill）會放大原本的問題、產生脆弱的 patchwork。
3. 推理失敗 2 次切到量測工具
靜態 CSS 推理 + 視覺截圖溝通的迴圈在第 1 次假設錯了之後成本就爆炸。第 2 次失敗主動提：起 server、用 playwright browser_evaluate 讀 live DOM。
工具切換 ROI 在第 1 次失敗後就轉正、不要等到第 5 次。簡單一次性確認用 DevTools、複雜或反覆 debug 用 playwright（可重跑、可寫成測試）。
4. 覆寫成本攤開、不偷偷對抗
當客製需求看似簡單但會對抗多層（UA stylesheet、framework CSS、browser default）— 在開始寫之前先報成本：「會打到哪幾層、要寫幾條規則、剩下什麼風險（升級會壞？瀏覽器差異？）」、讓使用者決定值不值。
不在使用者不知情的情況下堆 !important / specificity 戰 / 多層 polyfill — 沉默對抗會讓使用者驚訝於後續的維護負擔。
5. Revert 含 checkpoint、不直接清空
收到「先還原」「先重來」「換個方向」時、先確認：還原到哪個狀態？要不要先 commit 當前進度當 checkpoint（標「explored, not adopted」）？ 再執行 reset。
探索的成果即使沒採用、也是「為什麼不採用」的證據 — 直接清空會丟掉「下次別再走這條路」的判斷依據。
6. 漸進驗證、最小必要範圍
UI debug 從色塊 placeholder 起步（沒文字、沒樣式、單純色塊）→ 確認位置 / 尺寸 / grid 對 → 再加文字 → 再加樣式 → 再加互動。每階段只引入一個變數。
Selector / MutationObserver root / JS 操作邊界：從最小開始、有證據再擴張。「先寬後縮」分不出哪個寬度是刻意的；「先窄後寬」每次擴張都有原因。
7. Multi-pass Refinement：第 1 輪不追求完美、設計第 2 / 3 輪用不同 frame
第 1 輪實作預期會有未發現問題、不要追求 perfect — 跑得到結尾、看實際結果比寫得漂亮重要。第 2 輪用「對需求 / 邊界 case」frame、第 3 輪用「dogfood / 反向自查」frame、第 N 輪換「上層原則」frame。每輪不同 frame 才能 catch 上一輪 miss 的東西。
呈現決策時的「五維度展開」（references/decision-dialogue.md）就是 multi-pass 在「決策呈現」場景的具體實現：每維度等於一輪 self-check。「再仔細一次」≠ multi-pass — 同 frame 重看 catch 不到不同層的錯。L4 review / pair / dogfood 才是行為錯誤的解、不是再寫一條 hook（#82）。
When to Consult This Skill（觸發路由）
| 觸發情境 | 讀哪份 reference |
|---|
| 收到模糊指令（含「對齊」「靠近」「隔離」「不要動」「分開」等） | references/clarifying-ambiguous-instructions.md |
| 不確定某個決定該自決還是該先問使用者 | references/clarifying-ambiguous-instructions.md |
| 收到「依 X 篩選 / 只看 X / 過濾 Y」類指令、source 是分批的 | references/clarifying-ambiguous-instructions.md（類型 5：篩選三問） |
| 同方向失敗 ≥ 2 次、想再試一次更小心 | references/failure-pivot-protocol.md |
| 推理 + 視覺截圖溝通迴圈卡住、不知道該不該換工具 | references/tool-switching-timing.md |
| 客製需求要對抗多層（vendor CSS、framework、browser default） | references/cost-and-checkpoint.md |
| 收到「先還原 / 先重來 / 換個方向」類指令 | references/cost-and-checkpoint.md |
| 開始 UI layout debug、不知道從哪一步起 | references/progressive-verification.md |
| 設計 selector / MutationObserver root / JS 操作範圍 | references/progressive-verification.md |
| 準備呈現決策給使用者選擇（A 還是 B、要不要做 X） | references/decision-dialogue.md |
| 寫到「你想怎麼做？」「ABCDE 你選哪個？」這類開放問 | references/decision-dialogue.md |
| 反省題 / retrospective / 「下一步往哪走」類問題 | references/decision-dialogue.md |
每份 reference 自包含：以該情境為核心、把六大原則翻譯成可直接套用的協議步驟與模板。閱讀任一 reference 不需要回來看其他 reference。
Success Criteria（M1-M2 認知負擔類）
| Metric | 定義 | 目標 |
|---|
| M1 | 從 SKILL.md 出發、解決一個觸發情境需要開幾個檔案 | ≤ 2 |
| M2 | 隨機抽一份 reference、不讀其他 reference 能否獨立套用 | 100% |
Directory Index
requirement-protocol/
├── SKILL.md # 本檔：四支柱 + 七大原則速查 + 觸發路由
└── references/
├── clarifying-ambiguous-instructions.md # 情境 1：模糊指令的澄清協議（spatial / relative / isolation / decision-authority）
├── failure-pivot-protocol.md # 情境 2：失敗 2 次的轉折協議（停下、驗證假設、換方向）
├── cost-and-checkpoint.md # 情境 3：覆寫成本告知 + revert 含 checkpoint
├── progressive-verification.md # 情境 4：placeholder 漸進 + measurement 完整性 + 最小必要範圍
├── tool-switching-timing.md # 情境 5：推理 / DevTools / playwright 之間的切換時機
└── decision-dialogue.md # 情境 6：呈現決策的五維度協議（呈現 / 策略 / 批次 / 時間 / 選項類型）
Reading Order（建議閱讀順序）
- 第一次接觸 → 從本 SKILL.md 的「三大支柱 + 六大原則」讀起
- 進入實際情境 → 依觸發路由讀對應 reference（只讀一份）
- 想驗證自己有沒有套用對 → 用該 reference 結尾的 self-check checklist 自評
相關抽象層原則
本 skill 的協議建立在幾條抽象層原則上、實作協議時可背景引用（檔案位置：references/principles/）：
Last Updated: 2026-04-26
Version: 0.7.0 — Phase B1 結構升級：加第 4 pillar「Multi-pass Refinement」+ 第 7 原則、明示 multi-pass 在「需求協議」場景的展開、串連 #82 / #83 / #85
Version: 0.6.0 — 補 #82 (字面攔截 vs 行為精煉)：點出 hook 對行為錯誤無能為力、本 skill 的 reference + self-check + dogfood examples 就是 multi-pass 設計、不是「再補一條 hook 規則」
Version: 0.5.0 — 補 #80 (yes/no collapse) + #81 (卡片迭代浮現)、reference 加 dogfood examples 段（4 個 Bad/Good 對照）、#75 加 selector stacking 跨連 #46-#50
Version: 0.4.0 — 接入 #74-#79 決策協議系列：新增第 6 份 reference decision-dialogue.md（五維度：呈現 / 策略 / 批次 / 時間 / 選項類型）；觸發路由加 3 條入口（呈現決策 / 開放問 / 反省題）；相關抽象層原則段補 #69-#79
Version: 0.3.0 — 接入 #69-#73：相關抽象層原則段補 Test-First (#69)、URL state (#70)、tab order (#71)、外部觸發 meta (#72)、search 匹配模式 (#73)
Version: 0.2.0 — 接入 #55-#68 系列：clarifying-ambiguous-instructions 加第 5 類「篩選類」（呼應 #58）；觸發路由加篩選類入口；SKILL.md 加「相關抽象層原則」段（#42-45 + #67-68）
Version: 0.1.0 — 從 50+ 篇事後檢討萃取「需求 → 實作對話協議」這條主軸；五份 references 對應「模糊指令 / 失敗轉折 / 成本與 checkpoint / 漸進驗證 / 工具切換」五個情境
