clarify-loop

澄清循環

所有探索與規格化階段共用以下互動機制。

---

核心原則

1. 提問節奏依 batch 模式決定：
   • batch = 1（預設）：一次只問一題，不透露後續問題。
   • batch > 1：一次呈現 N 題（N = batch size），使用者在同一則訊息中回覆所有答案。
2. 每題附帶推薦。明確標示推薦選項與理由，讓使用者覺得「選推薦的就對了」。
3. 可推斷的內容直接寫入，不佔用提問、不需要使用者確認。
4. 保持節奏 — 問題→回答→下一題（或下一批）。不在中間插入大段說明、展示更新內容、或要求確認寫入結果。

---

通訊工具（依執行層級）

此 skill 定義的是問題內容的範本，實際「投遞」問題給用戶時，必須依執行層級選對工具，否則用戶看不到：

執行層級	偵測方式	通訊工具
主窗口	無上層 Agent tool 呼叫	直接輸出下方定義的 Markdown 範本；用戶可直接看到
Sub-agent（terminal）	由上層 Agent tool 啟動 + GITHUB_ACTIONS 未設或為 false	必須使用 AskUserQuestion 工具——sub-agent 的純文字輸出只會變成 tool result 回傳給上層，用戶 terminal 上看不到
Sub-agent（CI）	由上層 Agent tool 啟動 + GITHUB_ACTIONS=true	使用 gh issue comment 發問到 Issue 討論串

⚠️ 嚴禁 sub-agent 只輸出 Markdown 文字當作提問——那些文字用戶完全看不到，等於沒問。這是本 skill 最常見的誤用。

AskUserQuestion 對齊本 skill 格式

將本 skill 的 Markdown 範本映射到工具參數：

Markdown 範本	AskUserQuestion 參數
[QN/M] 問題描述	question / questionText 文字
**推薦：X** — 理由	在 question 文字尾加「（推薦：X — <理由>）」，並在對應 option 的 description 前綴加 (推薦)
| 選項 | 說明 | 表格每列	options 陣列一項（label = 選項代號或簡短名，description = 說明）
—（Markdown 無對應）	一律額外加入 其他（請簡述） option，允許用戶自由輸入

澄清紀錄（${CLARIFY_DIR}/ 的 session 檔案）仍以 Markdown 格式寫入，不受通訊工具影響。

---

提問格式

選擇題（優先使用）：

[Q3/10] <問題描述>

**推薦：B** — <1-2 句理由>

| 選項 | 說明 |
|------|------|
| A | <選項描述> |
| B | <選項描述> |
| C | <選項描述> |
| D | 其他（請簡述） |

回覆選項代號即可，或說「yes」接受推薦。

簡答題（僅在選項無意義時使用）：

[Q5/10] <問題描述>

**建議：** <你的建議答案> — <理由>

請提供簡短答案，或說「yes」接受建議。

---

批次提問格式（batch > 1 時使用）

當 batch > 1 時，一次呈現 N 題，每題獨立編號與推薦，使用者用代號逐題回覆：

[Q7] <問題描述>
**推薦：B** — <理由>
| 選項 | 說明 |
|------|------|
| A | ... |
| B | ... |

[Q8] <問題描述>
**推薦：A** — <理由>
| 選項 | 說明 |
|------|------|
| A | ... |
| B | ... |

[Q9] <問題描述>
**推薦：B** — <理由>
| 選項 | 說明 |
|------|------|
| A | ... |
| B | ... |

回覆格式：`Q7: B, Q8: A, Q9: yes`（或逐行回覆皆可）

簡答題混用：批次中可混合選擇題與簡答題，各題獨立標示格式。

---

回答處理

1. 使用者回覆 "yes" / "推薦" / "建議" → 採用你的推薦/建議。
2. 使用者選擇某選項 → 採用該選項。
3. 回答模糊 → 追問釐清（不計入問題計數）。
4. 採納後，先 append 澄清紀錄到 ${CLARIFY_DIR}/ 的當次 session 檔案，再靜默更新對應的產出檔案。不展示更新內容、不要求確認。
5. 執行 Consistency Sweep（由呼叫方的 Mini-plan step 6 定義）：掃描剩餘 CiC，移除已過時的便條紙，並向使用者顯示刪除原因。若有便條紙被移除，重新計算優先序。
6. 選取下一題（或下一批），進入下一輪。
7. 批次回答處理（batch > 1 時）：
   • 解析使用者的批次回覆（如 Q7: B, Q8: A, Q9: yes），逐題採納
   • 所有答案採納後，一次性執行 Mini-plan（合併所有答案的影響範圍）
   • 再執行一次 Consistency Sweep（掃描所有剩餘 CiC）
   • 選取下一批 N 題，進入下一輪

---

澄清紀錄

每次 session 開始時，在 ${CLARIFY_DIR}/ 建立一個新檔案，檔名為 <YYYY-MM-DD-HHMM>.md，立刻將使用者的原始 idea 寫入檔頭。每題回答採納後 append 一行：

# Clarify Session <YYYY-MM-DD HH:MM>

## Idea

<使用者原始 idea 全文，逐字複製，不摘要、不改寫>

## Q&A

- Q: <問題> → A: <最終答案>
- Q: <問題> → A: <最終答案>
- Q: <問題> → A: <最終答案>

---

提問上限與批次呈現

兩層控制：

維度	參數	預設	說明
Round（回合）	${MAX_QUESTIONS_PER_ROUND}	10	每回合的問題總數上限
Batch（批次）	${BATCH_SIZE}	1	每次同時呈現幾題

一個 Round 內，以 Batch 為單位分批呈現。例如 Round = 10、Batch = 3 → 跑 3~4 批。

批次開場（Round Opener）

每回合開始時，展示本回合的問題地圖（列出全部 N 題），讓使用者知道整個回合的全貌：

--- Round <R> 開始（共 <M> 張待解便條紙，本回合處理 <N> 張，每批 <B> 題）---

本回合問題地圖：
| # | 類型 | 位置摘要 | 優先分數 |
|---|------|---------|---------|
| Q1 | GAP | 觸發Stage晉升.feature | 12 |
| Q2 | GAP | 手動新增Lead.feature | 9 |
| ... | ... | ... | ... |

開始提問（第 1 批）：

然後依 ${BATCH_SIZE} 呈現第一批問題。使用者回覆後，處理答案 + Mini-plan + Consistency Sweep，再呈現下一批。

批次結尾（Round Closer）

回合內所有 Question 回答完畢（或達上限）時，展示回合進度摘要：

--- Round <R> 完成 ---

已解決 <A> 張便條紙（含 Consistency Sweep 自動移除 <B> 張）。
剩餘 <C> 張待解。

繼續下一回合？（回覆「繼續」或提出新問題）

Question 與 Sub-question 的區分

Question（計入上限）：為了推進新的追蹤地圖項目而提出的主要提問。計數器僅在切換至新的追蹤地圖項目時遞增。

Sub-question（不計入上限）：仍在解決同一個追蹤地圖項目的所有互動，包含：

• 回答模糊時的追問釐清
• 使用者回答後的延伸確認（僅在回答本身產生新歧義時）
• AI 針對同一項目主動追問的延伸細節
• 使用者糾正提案內容後的修正循環

判定原則：若問題仍在解決同一個追蹤地圖項目，則為 Sub-question。切換至新項目時才計為下一題 Question。