---
name: mp-grill-with-docs
description: |
  用追問把模糊需求壓成專案語言，並在必要時更新 CONTEXT.md 或 ADR。
  Use when: 需求還不清楚、術語不一致、要進 OpenSpec 前需要需求對齊、
  或使用者想先 stress-test plan 而不是直接實作。
---

# mp-grill-with-docs

本技能負責需求澄清、專案語言校準與決策沉澱。它位於 `openspec-*` 之前，不取代 OpenSpec proposal，也不直接進入實作。

## 核心原則

- 一次只問一個決策問題。
- 每個問題都附上你的建議與理由。
- 能從本地程式碼或文件查到答案時，先查，不要求使用者憑記憶回答。
- 只沉澱對專案語言有長期價值的內容。
- 不把單一實作細節寫進 `CONTEXT.md`。

## 啟動時先讀

依序檢查：

- `docs/agents/mp-workflow.md`
- `docs/agents/domain.md`
- `CONTEXT-MAP.md`
- `CONTEXT.md`
- `docs/adr/`
- 與需求相關的程式碼或文件

若 `docs/agents/` 不存在，提醒先執行 `mp-setup-matt-pocock-skills`。

## 追問方式

每輪只處理一個決策點：

1. 說明目前模糊點。
2. 提出你的建議答案。
3. 說明採用該建議的理由與取捨。
4. 問使用者是否接受，或要改成另一種說法。

常見追問方向：

- 詞彙是否已和 `CONTEXT.md` 一致。
- 同一個詞是否代表不同概念。
- 需求的成功與失敗條件是什麼。
- 哪些情境不應被納入本輪。
- 哪些決策會影響 OpenSpec proposal 或 tasks。

## 文件沉澱

### `CONTEXT.md`

當一個術語滿足以下條件時，才更新或建立 `CONTEXT.md`：

- 它是領域語言，不只是程式實作細節。
- 未來 agent 或人類會重複使用。
- 使用者已確認定義。

### ADR

只有三個條件都成立時才建立 ADR：

- 反悔成本高。
- 沒有背景會讓未來讀者困惑。
- 曾經有真實取捨，而不是顯而易見的決定。

若缺一項，記在對話或 OpenSpec artifact 即可，不建立 ADR。

## 輸出

結束時輸出：

- 已確認的專案語言。
- 已確認的決策。
- 尚未解決的問題。
- 建議下一步：`mp-to-prd`、`mp-to-issues`、或 `openspec-propose`。