# 设计循环方法论（Design Loop Method）

> Grilling 提问法、Question Hierarchy、交互原则、gap 信号等方法论详解。
> **首次执行本工作流（clarity 阶段）read 一次；后续阶段按 `loop-skeleton.md` 操作即可，无需重复 read 本文件。**
> 操作指令（6 步流程、subagent task prompt 模板、F/K/D 规则）见 `loop-skeleton.md`。

## 核心原则（完整 7 条）

1. **交互与追踪分离** — 主 agent 做交互（提问、给方案、写初稿），独立 subagent 做追踪（强制枚举视角）。主 agent 不做系统追踪——它带着对话上下文有确认偏误。
2. **强制视角是 forcing function** — 每个阶段定义自己的 N 视角。每个视角必须核对或写降级理由。视角清单在各 skill 的 references 文件中。
3. **F 类二次确认** — Fact gap 先经主 agent 确认（过滤误报），两边都认才问用户。K/D 直接问用户。
4. **收敛靠独立复核** — 停止条件是「独立 subagent 跑完视角追踪无新 gap」，不靠主 agent 自我判断。
5. **定稿后必须过独立审查** — Step 6 审查 subagent 从质量/一致性/可执行性维度判定稿是否合格，而非找 gap。审查通过才能交接下游。审查与追踪是两种不同的检查（追踪=完整性，审查=质量）。
6. **一次一个问题** — 用 `ask_user` 逐个解决 gap，不一次性抛出所有问题。
7. **决策是一等持久化公民（decisions.md）** — 用户拍板的决策即时 append 到 `{topic}/decisions.md`（append-only 账本），不靠对话痕迹传递。fresh subagent 通过 context 参数注入 decisions.md 拿到已确认决策，对抗主 agent context 被 compact。已 confirmed 决策不得当 gap 重报；推翻走 Step 6b 反哺（D-不可逆须 ask_user）。这是「fresh context 对抗 bias」与「主 agent 对抗 compact」的配套机制——前者靠隔离，后者靠持久化。

## Grilling 提问法（Step 1 详解）

移植自 grilling / grill-me skill——**对设计树的每个节点 relentless 追问，直到达成共识**。不是「问几个问题就停」，而是「沿着设计树走，一个分支一个分支地解决决策依赖」。

**四条铁律：**

1. **设计树遍历，不跳跃** — 把要澄清的主题展开成一棵设计树（根=核心目标，分支=子决策）。沿树枝从根到叶逐节点推进，**解决父节点再问子节点**。不在不同树枝间来回跳——跳跃会让用户困惑、遗漏依赖。

   > 例（澄清需求阶段）：根「业务目标」→ 分支「谁是 Actor」→ 叶「Actor A 有哪些用例」。先把 Actor 问清楚，再问 Actor A 的用例；不要 Actor 还没定就跳去问数据流。

2. **每个问题附推荐答案** — 不甩空问题菜单。每个问题给出**你的推荐答案 + 理由**（基于已建立的上下文和代码扫描）。用户要的是强观点，不是「你觉得呢？」。用户可以采纳、修正或推翻——但推荐答案让对话有锚点。

   > ❌「数据归档策略是什么？」
   > ✅「推荐按月分区 + 90 天后转冷存储（你现在的 orders 表已经按月分区了，沿用同一策略最省力）。除非有合规要求保留更久？」

3. **一次一个问题，等回答再继续** — 一次只问一个。抛多个问题 = 让用户认知过载 = 回答质量下降。一个主题需要深挖时，拆成连续的单问题序列。

4. **能查代码就查代码，不问用户** — 如果问题能通过探索代码库回答（「现在有没有 refund 表？」「状态枚举有哪些？」），**dispatch 只读 subagent 去查，不问用户**。问用户的问题应该是代码回答不了的（业务意图、取舍偏好、未来计划）。

**何时停止提问：** 当你能不猜测地向用户完整复述方案、且每个设计树叶子节点都有明确答案时。如果还有「大概是」「应该可以」「这取决于」，继续问。

### Question Hierarchy（按顺序提问）

**Layer 1: 目标与用户（2-3 问题）**
- 解决什么问题？谁受影响？
- 成功长什么样？怎么知道完成了？

**Layer 2: 核心行为（3-5 问题）**
- 走一遍主要流程。先发生什么，然后呢？
- [具体场景] 时应该发生什么？（基于回答提出具体场景）
- 和哪些现有功能/系统交互？
- 有硬约束吗？

**Layer 3: 边界与非显而易见（2-3 问题）**
- 明确不做什么？什么是 out of scope？
- 有已经做出的决策我不该重新讨论吗？

**各阶段特有的提问焦点** 见各自 SKILL.md 的「Step 1」章节——每个阶段有不同的设计树（业务目标树 / 架构决策树 / issue 决策树 / 副作用树 / 代码契约树 / Wave 依赖树）。

#### 写初稿

提问结束后，写初稿到阶段对应的产出文件（见各 skill 的「交付物」章节）。**初稿不追求完整** — 它是对话能聊清楚的部分的记录。遗漏的部分由 Step 2 的 subagent 发现。

## 交互原则（Grilling 快速参考）

- **一次一个问题** — 一个主题需要更多探索时，拆成多个问题
- **设计树遍历** — 沿树枝从根到叶推进，解决父节点再问子节点，不跳跃
- **每个问题给推荐答案** — 附推荐 + 理由，用户要强观点不是选项列表
- **优先多选** — 选项可发现时（来自 quick overview 或 scan）用 `ask_user` 多选
- **避免抽象问题** — 别问「需求是什么？」，问「用户点击 X 时，Y 应该立即发生还是确认后？」
- **能查代码就查代码** — 如果问题能通过探索代码回答，探索代码而不是问用户
- **快速浏览先于提问** — 提问前快速浏览项目（ls + 依赖文件 + README + CONTEXT.md），建立基本上下文，避免问已有答案的问题（< 30 秒）
- **relentless** — 还有「大概是」「应该可以」就继续问，直到每个设计树叶子节点都有明确答案

### On-demand Deep Scan（按需触发，贯穿 Step 1）

当用户回答涉及具体模块、技术细节或需要验证代码行为时，dispatch 只读 subagent 做针对性扫描。

**触发条件（任一）：**
- 用户提到「和 XX 模块交互」→ 扫描该模块
- 用户提到「复用现有的 YY 机制」→ 扫描相关代码
- 需要验证代码中是否存在某个功能/约束 → 精准 grep + read

**Subagent config:**

| Item | Value |
|------|-------|
| Agent | general-purpose (read-only mode) |
| Tools | read, bash (no write) |

Scan 结果直接用于后续提问，不产出独立文档。

## 审查 vs 追踪的区别

| | Step 2/4 追踪 | Step 6 审查 |
|---|---|---|
| **问什么** | 信息完不完整？有没有 gap？ | 质量行不行？能不能用？ |
| **输入** | 初稿（可能不完整） | 定稿 .md + .html（已完成） |
| **视角** | 强制枚举 N 视角（找遗漏） | 全局质量（判好坏） |
| **输出** | gap 列表（F/K/D） | verdict: APPROVED / CHANGES_REQUESTED |
| **失败动作** | 回 Step 3 补 gap | 回 Step 3（审查发现当 gap 处理）|

追踪找的是「缺了什么」，审查判的是「做出来的东西够不够好」。

## gap 卡住信号

追踪 subagent 遇到以下情况说明遇到了 gap：

1. **「我不知道」** → 需要信息才能继续追踪
2. **「大概是...」** → 在猜测，不是在追踪
3. **「应该可以...」** → 在假设，不是在确认
4. **「这不重要」** → 可能重要，记录为 gap 让主 agent 判断
5. **「这取决于...」** → 有未做的决策（D 类）
6. **「让我看看代码」** → F 类 gap，需要扫描源码