amadeus-dlc/amadeus

amadeus-grilling

目的

透過提問，逐一消除計劃與設計中的模糊地帶。

直到達成共享理解為止，依序追溯設計樹的分支。 互相依賴的判斷，則在釐清依賴關係後逐一解決。

基本態度

提問應嚴謹執行。 但提問本身不應成為目的。

只詢問使用者必須判斷才能繼續進行的項目。 能從程式碼庫、.amadeus/ 產出物、既有文件、既有對話中推得的答案，則不須提問，由自身確認。

提問方式

一次只問一個問題。 若同時提出多個問題，會難以判斷應先解決哪一個。

每個問題應包含以下內容：

• 想要決定什麼。
• 為什麼現在需要這個判斷。
• 推薦的回答。
• 推薦的理由。

提問後，等待使用者回應。 在收到回應之前，不得進行下一個問題。

推薦回答

每個問題都必須附上推薦回答。

推薦回答應根據目前的產出物、設計邊界、實作風險以及對後續工作的影響來提出。 若無法推薦，則應說明原因以及判斷所需但不足的資訊。

調查優先

若問題能透過調查程式碼庫或產出物來回答，則應優先調查。

調查對象範例：

• .amadeus/
• README.md
• AGENTS.md
• AMADEUS.md
• 既有的 skill
• 既有的 Intent 產出物
• 既有的 domain、glossary、decision、traceability

調查後，只有在仍需要人類判斷時才提問。

Grilling Decision Trail

在 guided 或 refine 模式下，若問題與回答對產出物的意義或後續判斷有影響，則應將確定的判斷過程記錄為 Grilling Decision Trail。

Grilling Decision Trail 並非原始日誌。 未確定的發言、途中被否決的方案、單純的執行許可、工作順序的輕微確認、命令執行的確認、暫時性的作業方便，皆不記錄。

記錄對象為以下類型的判斷：

• 範圍。
• 成功條件。
• 排除事項。
• 依賴關係。
• 術語。
• 界定上下文（Bounded Context）。
• 分割方針。
• 狀態判斷。
• 反映目標。
• supersede 判斷。

amadeus-grilling 是用於記錄對象、記錄結構、狀態以及編號的準則。 實際的 grillings.md 與 grillings/Gxxx-*.md 的建立或更新，則由呼叫 grill 的 phase skill 負責。

在提問的回合中，不更新產出物。 在收到使用者回應的下一個回合中，phase skill 會在其產出物邊界內解讀回應，並在更新 phase 產出物的同時，以相同的變更更新 Grilling Decision Trail。

存放位置為目標產出物集合的根目錄正下方。

<目標 root>/
  grillings.md
  grillings/
    G001-<topic>.md

目標 root 為：

.amadeus/discoveries/<discovery-id>/
.amadeus/event-storming/<event-storming-id>/
.amadeus/intents/<intent-id>-<slug>/
.amadeus/intents/<intent-id>-<slug>/event-storming/<event-storming-id>/

Steering layer 因現行 .amadeus/ 目錄結構混雜，故排除在此記錄對象之外。

僅影響整體領域或共享術語的判斷，在現行結構下不另設專屬的 Grilling Decision Trail。 必要時，可記錄於 .amadeus/domain-map.md、.amadeus/context-map.md、.amadeus/glossary.md 的依據，或目標 Intent 的 decision 中。

grillings.md 僅處理索引。 Session 詳細內容應置於 grillings/Gxxx-*.md。

grillings.md 應具備以下最低結構：

# Grillings

## 一覽表

| ID | 主題 | 目標 | 狀態 | 主要確定判斷 | 反映目標 | 詳細 |
|---|---|---|---|---|---|---|
| G001 | Ideation Scope | Intent | completed | 目標範圍限定於管理畫面 | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

Session 檔案名稱應為 G001-<topic>.md。 <topic> 僅使用英文小寫字母、數字和連字號。

Session 狀態為下列其中之一：

• active
• completed
• superseded

個別判斷的狀態為下列其中之一：

• active
• superseded

Session 檔案應包含 概要、確定判斷、提問記錄。 概要 必須寫明整個 Session 的反映目標。 概要 與個別判斷的反映目標，應指向目標 root 內的產出物。 對於 Discovery 與 Event Storming，允許從 <id>/grillings 指向相同 ID 的父層 Markdown 檔案，如 ../<id>.md。 但僅限於從整體領域下的 Grilling Decision Trail 指向 .amadeus/glossary.md 時，才允許作為共享術語的反映目標，使用 ../glossary.md。 每個提問記錄必須包含 想確認的事項、需要確認的理由、推薦回答、推薦理由、使用者回應。 每個提問記錄必須引用確定判斷的 ID。 個別判斷必須寫明反映目標。 被 superseded 的個別判斷必須寫明取代目標。

在 scaffold-only 模式下不進行提問，因此不建立 Grilling Decision Trail。 在 repair 模式下原則上不更新 Grilling Decision Trail。 但若既有的 grillings.md 或 grillings/Gxxx-*.md 本身已損壞，則可作為結構修復而進行修正。

長期討論的交接

若 grilling 進程長期化，且分開至不同對話單位繼續進行較安全時，可使用 handoff 作為輔助工具。

handoff 不屬於 Amadeus DLC 的產出物。 建立的交接文件應置於作業系統的暫存目錄中，不得置於 .amadeus/ 目錄下。

已確定的判斷應保留於 Grilling Decision Trail 中。 handoff 僅包含在下一個對話單位中重新開始所需參照的參考資訊。

handoff 至少應包含以下內容：

• 目標 workspace 與目標產出物集合。
• 應參照的 grillings.md 與 grillings/Gxxx-*.md。
• 已確定判斷的摘要。
• 尚未回答的問題，以及下一個應確認的問題。
• 下一個對話單位推薦使用的 skill。

請勿將既有產出物中已撰寫的內容重複複製到 handoff 中。 若已有產出物、PR、Issue、差異比較或驗證結果，則應以路徑或 URL 進行參照。

在 Amadeus 中的使用時機

適用於以下場景：

• 確認 steering layer 的目的、參與者、限制與領域範圍。
• 確認 Intent 的目的、依賴關係、成功條件與範圍。
• 確認 Ideation 的目標範圍、排除事項、可行性、團隊組成、初期 Mock 以及移交給 Inception 的內容。
• 確認術語、概念、界定上下文、DDD 模型、合約的意義。
• 確認 Unit、Bolt、Spec 的粒度或例外原因。

禁止事項

• 不得同時提出多個問題。
• 不得詢問能夠透過閱讀既有產出物得知的事項。
• 不得在沒有推薦回答的情況下提問。
• 不得在提問回合中，尚未等待回應就更新產出物。
• 不得將使用者的回應與既有產出物矛盾地確定下來。若有矛盾，應先說明矛盾之處並進行確認。