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 不是原始日志。 不记录：未确定的言论、中途被否定的方案、单纯的执行许可、工作顺序的简单确认、命令执行的确认、临时的工作便利事项。

记录对象是以下类型的决策：

• 范围。
• 成功条件。
• 排除项。
• 依赖关系。
• 术语。
• 有界上下文。
• 拆分策略。
• 状态判断。
• 反映目标。
• 替代（supersede）判断。

amadeus-grilling 定义了记录对象、记录结构、状态和编号规则。 实际的 grillings.md 和 grillings/Gxxx-*.md 的创建或更新，由调用 grilling 的 phase skill 负责。

在提问的那个回合，不更新产物。 在收到用户回答后的下一个回合，phase skill 在其自己的产物边界内解释回答，并在更新 phase 产物的同时，进行相同的变更来更新 Grilling Decision Trail。

位置放在目标产物集的根目录下。

<目标根目录>/
  grillings.md
  grillings/
    G001-<主题>.md

目标根目录如下：

.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 仅作为索引使用。 会话详情放在 grillings/Gxxx-*.md 中。

grillings.md 需具有以下最小结构：

# Grillings

## 列表

| ID | 主题 | 目标 | 状态 | 主要已确定决策 | 反映目标 | 详情 |
|---|---|---|---|---|---|---|
| G001 | Ideation Scope | Intent | completed | 目标范围限定为管理界面 | [scope.md](scope.md) | [G001](grillings/G001-ideation-scope.md) |

会话文件命名为 G001-<主题>.md。 <主题> 仅使用英文小写字母、数字和短横线。

会话状态为以下之一：

• active
• completed
• superseded

单个决策的状态为以下之一：

• active
• superseded

会话文件中需包含 概要、已确定决策、提问记录。 概要 中必须写明整个会话的反映目标。 概要 和单个决策的反映目标，指向目标根目录内的产物。 在 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 的产物。 创建的交接文档放在 OS 的临时目录中，不要放在 .amadeus/ 目录下。

已确定的决策保留在 Grinding Decision Trail 中。 handoff 仅包含在下一个会话单元中重新开始所需的相关引用。

handoff 至少应包含以下内容：

• 目标 workspace 和目标产物集。
• 应引用的 grillings.md 和 grillings/Gxxx-*.md。
• 已经确定的决策摘要。
• 未回答的问题以及需要确认的下一个问题。
• 下一个会话单元推荐的 skill。

不要将已在现有产物中包含的内容重复写入 handoff。 如果存在产物、PR、Issue、差异、验证结果，则通过路径或 URL 进行引用。

在 Amadeus 中的使用场景

在以下场景中使用：

• 确认 steering layer 的目的、参与者、约束、领域范围。
• 确认 Intent 的目的、依赖关系、成功条件、范围。
• 确认 Ideation 的目标、排除项、可行性、团队构成、初始原型、向 Inception 的交接事项。
• 确认术语、概念、有界上下文、DDD 模型、契约的含义。
• 确认 Unit、Bolt、Spec 的粒度或例外理由。

禁止事项

• 不要同时提出多个问题。
• 不要询问那些通过阅读现有产物就能知道答案的问题。
• 不要在没有推荐答案的情况下提问。
• 不要在提问的回合中，不等回答就更新产物。
• 不要以与现有产物矛盾的方式确认用户的回答。如果存在矛盾，先解释矛盾，然后进行确认。