@namewta/speculo 0.2.2 → 0.2.6

package/template/workflows/specdev/D-diagnose-bugs/cleanup-postmortem.md

@@ -0,0 +1,37 @@
+# 清理与事后分析
+
+诊断完成、修复已由 I-implement 执行后，必须完成以下清理和复盘。
+
+## 清理检查清单
+
+逐项确认：
+
+- [ ] 原始复现不再复现——重新运行阶段 2 的反馈回路，确认变绿
+- [ ] 回归测试通过——I-implement 已为修复编写并通过回归测试
+- [ ] 所有 `[DEBUG-xxxx]` 插桩已移除——`grep -r "\[DEBUG-"` 项目根目录，确认无残留
+- [ ] 一次性原型已删除——移除所有为诊断创建的临时脚本、测试夹具、mock 数据
+- [ ] 被证实的假设已记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`，以便下一个调试者学习
+
+## 记录根因
+
+在 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 中追加条目：
+
+```markdown
+## [YYYY-MM-DD] 诊断：<bug 简述>
+
+- **根因**：<被证实的假设，包含技术细节>
+- **验证方式**：<哪个探测确认了根因>
+- **修复提交**：<I-implement 的提交 hash 或描述>
+- **预防建议**：<什么本可以预防此 bug>
+```
+
+## 事后分析
+
+问：什么本可以预防这个 bug？从以下维度审视：
+
+- **测试缝合点**——是否缺少合适的测试接缝？如果有好的缝合点，此 bug 是否会被更早发现？
+- **接口设计**——接口是否暴露了容易误用的契约？深度是否足够防止调用者犯错？
+- **数据边界**——是否缺少输入校验、类型约束或边界条件处理？
+- **耦合**——是否因模块间的隐藏耦合导致变更的连锁反应？
+
+如果答案涉及架构变更（没有好的测试缝合点、纠缠的调用者、隐藏的耦合），将具体情况记录到 LOG.md 的预防建议中。在修复之后提出建议——此时比诊断开始时拥有更多信息。

package/template/workflows/specdev/D-diagnose-bugs/feedback-loop-techniques.md

@@ -0,0 +1,84 @@
+# 反馈回路构建技术
+
+反馈回路是诊断的核心——一个紧凑的通过/失败信号，锚定 bug 的症状。以下技术按大致优先级排列，从最理想到最后手段。
+
+## 构建方式
+
+按顺序尝试，直到获得一个可工作的回路：
+
+### 1. 失败测试
+
+在能触及 bug 的任意缝合点编写——单元测试、集成测试、端到端测试。优先选择现有的测试缝合点。观察项目中已有的测试了解如何注入测试。
+
+### 2. Curl / HTTP 脚本
+
+针对正在运行的开发服务器。固定请求参数，对响应状态码和关键字段进行断言。
+
+### 3. CLI 调用
+
+带固定输入调用 CLI，将 stdout 与已知良好快照进行 diff。适合命令行工具和数据管道。
+
+### 4. 无头浏览器脚本
+
+Playwright 或 Puppeteer 驱动 UI，对 DOM 状态、控制台输出、网络请求进行断言。适合前端 bug。
+
+### 5. 回放捕获的追踪数据
+
+将真实网络请求、负载、事件日志保存到磁盘，在隔离环境中通过代码路径回放。适合需要真实数据的场景。
+
+### 6. 一次性测试夹具
+
+启动系统的最小子集——一个服务、模拟依赖——用单个函数调用驱动 bug 代码路径。适合微服务或多组件交互的 bug。
+
+### 7. 属性 / 模糊测试循环
+
+如果 bug 表现为"有时输出错误"，运行 1000 次随机输入寻找故障模式。适合数据相关或边界条件 bug。
+
+### 8. 二分查找夹具
+
+如果 bug 出现在两个已知状态之间（commit、数据集、版本），自动化"在状态 X 启动、检查、重复"以便 `git bisect run`。
+
+### 9. 差分循环
+
+通过旧版本 vs 新版本（或两种配置）运行相同输入，对输出进行 diff。适合回归 bug。
+
+### 10. HITL bash 脚本
+
+最后手段。如果必须由人工点击，使用 `<Path>{roots.vendor}/matt-pocock/engineering/diagnosing-bugs/scripts/hitl-loop.template.sh</Path>` 驱动人工操作，使循环仍然结构化。捕获的输出反馈给 agent。
+
+复制模板，编辑步骤，运行脚本。脚本中的 `step` 函数显示指令并等待按 Enter，`capture` 函数显示问题并读取响应。结束时以 `KEY=VALUE` 格式打印捕获的值供 agent 解析。
+
+## 收紧回路
+
+将回路视为产品。一旦有了一个回路，收紧它：
+
+- **更快**——缓存设置、跳过无关初始化、缩小测试范围
+- **更清晰**——针对具体症状断言，而非"没崩溃"
+- **更确定**——固定时间、种子随机数、隔离文件系统、冻结网络
+
+一个 30 秒的抖动回路比没有回路好不了多少；一个 2 秒的确定性回路是调试的超能力。
+
+## 非确定性 bug
+
+目标不是干净的复现，而是更高的复现率。循环触发 100 次，并行化，增加压力，缩小时间窗口，注入 sleep。50% 抖动的 bug 是可调试的；1% 则不行——持续提高复现率直到可调试。
+
+## 当确实无法构建回路时
+
+停下来，明确说明。列出已尝试的方法。向用户请求：
+
+1. 访问能复现的任何环境
+2. 一个捕获的产物——HAR 文件、日志转储、核心转储、带时间戳的屏幕录制
+3. 添加临时生产环境插桩的许可
+
+在没有回路的情况下进入假设阶段是本规程要防止的核心失败模式。没有变红能力的命令，就没有后续阶段。
+
+## 最小化协议
+
+复现后，将场景缩小到仍能变红的最小场景。逐个削减以下元素，每次削减后重新运行回路：
+
+1. 输入数据——减少字段、缩小数据集、简化参数
+2. 调用者——移除中间层、直接调用核心逻辑
+3. 配置——使用默认值、移除环境变量
+4. 步骤——跳过前置操作、合并中间步骤
+
+每个剩余元素必须有负载作用——移除其中任何一个都会使回路变绿。最小复现场景缩小了假设空间，并成为最终的回归测试基础。

package/template/workflows/specdev/D-diagnose-bugs/hypothesis-format.md

@@ -0,0 +1,46 @@
+# 假设格式与诊断计划
+
+在插桩之前生成多个排名假设。单一假设会锚定在第一个看似合理的想法上。每个假设必须是可证伪的——陈述其预测。
+
+## 假设格式
+
+每个假设使用以下模板：
+
+> 如果 `<根因>` 是原因，那么 `<改变 X>` 会使 bug 消失 / `<改变 Z>` 会使它更糟。
+
+无法陈述预测的假设只是感觉——精炼或丢弃它。
+
+示例：
+
+> 如果缓存键在用户 ID 包含特殊字符时生成错误，那么将用户 ID 替换为纯字母数字字符串会使 bug 消失，而保持原 ID 并在缓存查询前打印键值会显示格式错误的键。
+
+## 排名规则
+
+生成 3-5 个假设，按以下优先级排名：
+
+1. **最近变更**——最近修改的代码区域优先。新代码是 bug 最常见的来源。
+2. **数据边界**——涉及空值、特殊字符、极限值、类型转换的假设优先于一般逻辑错误。
+3. **时序与并发**——涉及竞态条件、异步顺序、超时的假设在单线程同步假设之后。
+4. **外部依赖**——涉及第三方库、API 响应变更、环境差异的假设排在最后。
+
+## 诊断计划呈现
+
+将排名假设列表作为诊断计划呈现给用户。使用以下格式：
+
+```markdown
+## 诊断计划
+
+基于当前症状和代码库理解，以下是 3-5 个按优先级排名的可证伪假设：
+
+1. **[假设名称]** —— 如果 `<根因>` 是原因，那么 `<预测>`。
+2. **[假设名称]** —— 如果 `<根因>` 是原因，那么 `<预测>`。
+...
+
+请确认计划或调整优先级。你是否已经排除了其中任何一个？
+```
+
+用户通常拥有能立即重排名的领域知识——低成本检查点，大幅节省时间。向用户展示后等待确认。
+
+## AFK 默认行为
+
+如果用户 AFK（无响应），按排名继续——从排名最高的假设开始插桩验证。在每个假设被排除后，更新排名并继续下一个，无需等待确认。

package/template/workflows/specdev/D-diagnose-bugs/instrumentation-rules.md

@@ -0,0 +1,51 @@
+# 插桩验证规则
+
+每个探测必须映射到诊断计划中的一个具体预测。每次只改变一个变量。
+
+## 探测映射
+
+在添加任何插桩之前，明确陈述：
+
+- 此探测验证诊断计划中的哪个假设、哪个预测
+- 期望看到什么结果（如果假设正确）
+- 期望看到什么结果（如果假设错误）
+
+每次探测后记录实际结果，与预测对照。如果预测不匹配，该假设被排除，移至下一个。
+
+## 工具偏好
+
+按优先级选择插桩方式：
+
+### 1. 调试器 / REPL 检查
+
+如果环境支持，优先使用。一个断点胜过十行日志。在关键路径上设置条件断点，检查变量状态和调用栈。
+
+### 2. 针对性日志
+
+在能区分假设的边界处添加日志——模块接口、数据转换点、分支条件。日志内容应包含：
+
+- 所在假设的简短标识
+- 关键变量的值
+- 与预测相关的状态信息
+
+### 3. 每条日志必须有明确的验证目标
+
+全量日志淹没信号。每条日志单独对应一个假设预测，通过唯一前缀追溯到诊断计划中的具体条目。
+
+## 调试日志标记
+
+所有调试日志使用唯一前缀标记，格式为 `[DEBUG-xxxx]`，其中 `xxxx` 为 4 位随机字母数字（如 `[DEBUG-a4f2]`）。在日志消息中包含：
+
+```javascript
+console.log(`[DEBUG-a4f2] 缓存键: ${cacheKey}, 用户ID: ${userId}`)
+```
+
+最终的清理只需一次 `grep`——未标记的日志保留，已标记的日志删除。
+
+## 性能分支
+
+对于性能回归，日志通常是错误工具。替代方案：
+
+1. 建立基线测量——计时夹具、`performance.now()`、分析器、查询计划
+2. 二分查找——定位引入回归的变更点
+3. 先测量，后修复——在没有测量基线的情况下，任何优化都是猜测

package/template/workflows/specdev/G-grill-with-docs/G-grill-with-docs.md

@@ -0,0 +1,54 @@
+---
+id: specdev/grill-with-docs
+type: workflow-entry
+workflow: specdev
+name: 设计访谈（带文档）
+description: 无情访谈打磨设计，同时持续产出 ADR.md、LOG.md 和 CONTEXT.md 三个领域文档。在设计讨论中捕获术语定义、记录架构决策、保存完整设计轨迹。
+keywords: [设计, 访谈, 领域建模, ADR, 决策记录, 词汇表, 设计轨迹]
+---
+
+# 设计访谈（带文档）
+
+组合 work——grilling 访谈技术 + domain-modeling 领域建模规程，在无情盘问中打磨设计，同时持续写入 ADR.md、LOG.md 和 CONTEXT.md 三个领域文档。访谈负责深度提问与共识达成，领域建模负责在决策结晶的瞬间捕获术语、记录轨迹、筛选架构决策。
+
+产物统一写入 `<Path>{roots.state}/specdev/changes/{change}/</Path>`，其中 `{change}` 为 `<YYYY-MM-DD>-<topic>` 格式。
+
+## 流程
+
+### 1. 启动变更
+
+创建 `<Path>{roots.state}/specdev/changes/{change}/</Path>` 目录（`{change}` 为 `<YYYY-MM-DD>-<topic>` 格式），初始化三个空文件模板：
+
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` — 架构决策记录，仅含 `# 架构决策记录` 标题
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` — 设计决策日志，含 `# 设计决策日志` 标题及维护规则说明
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` — 领域词汇表，含 `# {主题} 领域词汇表` 标题及一两句描述
+
+**完成标准**：变更目录 `<YYYY-MM-DD>-<topic>` 已创建，初始 ADR.md/LOG.md/CONTEXT.md 已就位。
+
+### 2. 访谈
+
+委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>`。一次一问，沿设计树逐分支推进，在用户确认共识之前不执行方案。访谈过程中随时更新 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`，记录每个确认、延后、替代的结论。
+
+**完成标准**：访谈完成——一次一问，决策树已遍历，共识已达成。LOG.md 已同步所有访谈结论。
+
+### 3. 捕获文档
+
+委托给 `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>`。对照词汇表挑战术语、精炼模糊语言、讨论具体场景、与代码交叉引用。
+
+- `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 同步所有结论
+- `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 精炼术语定义
+- `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 仅追加满足三条件的架构决策（参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`）
+
+**完成标准**：LOG.md 已同步所有结论；CONTEXT.md 已精炼术语；ADR.md 已追加满足三条件的架构决策。
+
+## 子文件引用
+
+本入口及以下子文件按需加载：
+
+| 文件 | 触发条件 |
+|------|----------|
+| `<Path>{roots.workflows}/specdev/G-grill-with-docs/grilling-protocol.md</Path>` | 进入步骤 2「访谈」时加载——包含完整访谈协议，一次一问、推荐答案、决策树遍历、LOG.md 同步规则 |
+| `<Path>{roots.workflows}/specdev/G-grill-with-docs/domain-modeling-rules.md</Path>` | 进入步骤 3「捕获文档」时加载——包含三文件分工、对照词汇表挑战、精炼与交叉引用规程、同步规则 |
+| `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>` | 需要创建或修改 ADR 条目时加载——单一 ADR.md 文件格式、编号规则、三条件检查、可选元素 |
+| `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>` | 需要增删改术语时加载——CONTEXT.md 结构、定义规则、增删改操作说明 |
+| `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>` | 需要记录设计结论时加载——LOG.md 格式、状态标记、编号规则、追加与修订规程 |

package/template/workflows/specdev/G-grill-with-docs/adr-format.md

@@ -0,0 +1,77 @@
+# ADR.md 格式
+
+所有架构决策记录存放在变更目录的单一 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 文件中。不使用 `docs/adr/` 目录下的编号文件，所有决策在一个文件内按二级标题分段。
+
+## 模板
+
+```md
+# 架构决策记录
+
+## 0001: {决策的简短标题}
+
+{1-3 句话：背景是什么，我们做了什么决策，以及为什么。}
+
+---
+
+## 0002: {另一决策标题}
+
+{1-3 句话描述。}
+
+---
+```
+
+每个决策是一个 `##` 二级标题，编号从 `0001` 开始顺序递增。决策之间用 `---` 分隔。
+
+就这样。一个 ADR 条目可以就是一个段落。其价值在于记录*已经*做出了决策以及*为什么*——而不是填满各个部分。
+
+## 追加新决策
+
+1. 读取 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`，找到最高现有编号
+2. 编号加 1
+3. 在文件末尾追加 `---` 分隔线和新条目
+
+## 可选附加元素
+
+仅当它们真正增加价值时才包含这些。大多数 ADR 不需要它们：
+
+- **日期**——在标题行的 `{标题}` 后面加 `（YYYY-MM-DD）`
+- **Status**——`**Status**: proposed | accepted | deprecated | superseded by ADR-NNNN`。当决策被重新审视时，直接修改状态标记
+- **Considered Options**——仅当被拒绝的替代方案值得记住时
+- **Consequences**——仅当需要指出非显而易见的下游影响时
+
+### 带可选元素的示例
+
+```md
+## 0003: 写模型采用事件溯源（2025-03-15）
+
+**Status**: accepted
+
+Order 聚合需要完整的变更历史用于审计和补偿。我们选择事件溯源——
+所有状态变更作为不可变事件存储，当前状态从中投影。
+
+**Considered Options**:
+- 事件溯源（已选）——天然审计日志，支持时间旅行调试
+- CRUD + 审计表——更简单，但审计日志与业务逻辑解耦，容易不同步
+- 仅 CRUD——无审计历史，不满足合规要求
+
+**Consequences**:
+- 写路径复杂度增加；读路径需要投影
+- 事件 schema 演进需要显式版本策略
+```
+
+## 修改已有决策
+
+- **澄清或补充后果**——直接编辑条目正文
+- **改变状态**——修改 `**Status**` 字段（如 accepted → deprecated）
+- **废弃**——将状态改为 `deprecated`，如被新决策替代则加上 `superseded by ADR-NNNN`
+- **不要删除**——即使决策被废弃，保留条目作为历史上下文
+
+## 三条件检查
+
+在创建 ADR 之前，确认以下三个条件同时为真：
+
+1. **难以逆转**——以后改变主意的成本是实质性的。容易逆转的决策跳过——你反正会逆转的。
+2. **没有上下文的话令人惊讶**——未来的读者会看着代码想"他们到底为什么这样做？"。不令人惊讶的决策没人会追问，不需要记录。
+3. **真实权衡的结果**——确实存在替代方案，你基于特定原因选择了一个。没有真正的替代方案就没有可记录的，除了"我们做了显而易见的事"。
+
+如果决策不满足全部三个条件，只记入 LOG.md，不追加 ADR。

package/template/workflows/specdev/G-grill-with-docs/context-format.md

@@ -0,0 +1,63 @@
+# CONTEXT.md 格式
+
+领域词汇表存放在变更目录的 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 中。它只包含精炼的规范术语定义，不包含实现细节、设计决策或草稿内容。
+
+## 模板
+
+```md
+# {项目名称} 领域词汇表
+
+{对该上下文是什么以及为什么存在的一两句话描述。}
+
+## {术语分组}
+
+**Order**：
+{对该术语的一两句话描述}
+_Avoid_: Purchase, transaction
+
+**Invoice**：
+发货后发送给客户的付款请求。
+_Avoid_: Bill, payment request
+
+**Customer**：
+下订单的个人或组织。
+_Avoid_: Client, buyer, account
+```
+
+## 规则
+
+- **要有主见。** 当同一概念存在多个词时，选择最好的那个，并将其他的列在 `_Avoid_` 下。不要犹豫——明确选定一个规范术语。
+- **定义保持精炼。** 最多一两句话。定义它是什么，而不是它做什么。术语的定义描述概念的本质，而非其行为或实现。
+- **仅包含特定于该项目上下文的术语。** 通用的编程概念（超时、错误类型、工具模式）即使项目广泛使用也不属于这里。添加术语前自问：这是该上下文独有的概念，还是一个通用编程概念？只有前者才属于这里。
+- **当自然形成聚类时，用子标题分组术语。** 如果所有术语属于一个单一的凝聚领域，扁平列表也可以。当术语数量超过 10 个时，几乎总能找到自然分组。
+- **随时增删改。** 模型演进时，直接修改文件：添加新术语、删除废弃术语、修正定义、术语更名。不要堆积——保持词汇表精炼且反映当前模型。
+
+## 增删改操作
+
+### 新增术语
+
+在合适的子标题下追加条目。如果现有子标题都不匹配，新建一个子标题。格式：
+
+```md
+**{术语名}**：
+{定义}
+_Avoid_: {避免使用的同义词，用逗号分隔}
+```
+
+### 修改术语
+
+直接更新定义文本和 `_Avoid_` 列表。如果术语的含义已经变化，更新定义以反映当前理解。在 `_Avoid_` 中添加新出现的同义词，移除不再使用的同义词。
+
+### 删除术语
+
+移除整个条目（术语名、定义、`_Avoid_` 行）。如果术语已不再使用或已被其他术语替代，直接删除，不要保留废弃标记。词汇表只反映当前模型。
+
+### 术语更名
+
+删除旧条目，新增新条目。在 `_Avoid_` 中保留旧名称作为新术语的避免项——这样未来的读者能理解新旧术语的对应关系。例如，将 "Client" 更名为 "Customer"：
+
+```md
+**Customer**：
+下订单的个人或组织。
+_Avoid_: Client, buyer, account
+```

package/template/workflows/specdev/G-grill-with-docs/domain-modeling-rules.md

@@ -0,0 +1,93 @@
+# 领域建模规程
+
+在设计过程中积极构建和精炼项目的领域模型。这是*主动*规程——挑战术语、发明边界场景、并在决策结晶的那一刻立即写入词汇表和决策。仅仅*阅读*文档获取词汇不是本规程——本规程用于当你正在*改变*模型，而不仅仅是消费它时。
+
+## 三文件分工
+
+三个文件各司其职，三者关系为：LOG.md 是最完整的记录 → CONTEXT.md 从中提取术语定义 → ADR.md 从中筛选同时满足三个条件的架构决策。
+
+| 文件 | 职责 | 维护方式 |
+|------|------|----------|
+| `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` | 完整设计轨迹——所有确认、延后、被替代的结论 | 持续增删改，条目可被后续决定修订 |
+| `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` | 精炼的规范词汇表——只保留当前有效的术语 | 增删改，保持精炼 |
+| `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` | 难以逆转、令人意外、存在真实权衡的架构决策 | 只追加不删除，可标记废弃 |
+
+## 对照词汇表挑战
+
+当用户使用的术语与 `CONTEXT.md` 中的现有语言冲突时，立即指出。"你的词汇表将 'cancellation' 定义为 X，但你似乎指的是 Y——到底是哪个？"如果用户确认应修改词汇表，更新 `CONTEXT.md` 中的定义并追加日志。
+
+## 精炼模糊语言
+
+当用户使用含糊或重载的术语时，提出一个精确的规范术语。"你在说 'account'——你指的是 Customer 还是 User？它们是不同的东西。"在 `CONTEXT.md` 中为新术语添加条目，将模糊的同义词列入 `_Avoid_`。
+
+## 讨论具体场景
+
+当讨论领域关系时，用具体场景进行压力测试。发明探索边界情况的场景，迫使用户精确界定概念之间的边界。"你说订单可以部分取消——未取消的商品怎么办？它们还能发货吗？"
+
+## 与代码交叉引用
+
+当用户陈述某事如何工作时，检查代码是否一致。如果发现矛盾，指出来："你的代码取消的是整个 Order，但你刚才说部分取消是可能的——哪个是正确的？"在日志中记录这种矛盾的发现和解决过程。
+
+## 及时更新 LOG.md
+
+当设计问答中形成任何结论时，当场更新 `LOG.md`。它是完整的设计轨迹——记录"当时讨论了什么、最终固定了什么行为以及对应哪个 ADR"。不要批量处理——发生时立即捕获。具体格式参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`。
+
+### 日志条目格式
+
+每条日志使用 `## LOG-XXXX: {标题}` 二级标题，编号从 `0001` 开始顺序递增。每个条目包含：
+
+- **Status** — `accepted`（已确认）、`deferred`（暂不决定）、`superseded`（被后续决定替代）
+- **Superseded by** — 如状态为 `superseded`，标注替代它的日志编号
+- **Related** — 如该结论对应某个 ADR，标注 `Related: ADR-XXXX`
+- **正文** — 背景、讨论的问题、做出的决定及原因，可以记录具体场景和交互细节
+
+### 维护规则
+
+- 每次完成设计问答，同步更新 `LOG.md`、`CONTEXT.md` 与 `ADR.md`。
+- 后续确认改变既有结论时，直接修订原日志条目，并记录替代关系，不保留互相矛盾的"现行规则"。
+- 日志可以记录具体交互和边界场景；词汇表保持精炼；ADR 只记录难以逆转、令人意外且存在真实权衡的决定。
+- 每个日志条目应关联对应的 ADR（如有）：`Related: ADR-XXXX`。
+- 状态为 `deferred` 的条目保留，以便后续恢复讨论时知道从什么问题开始。
+
+## 及时更新 CONTEXT.md
+
+当术语确定时，当场更新 `CONTEXT.md`。不要批量处理——发生时立即捕获。具体格式参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/context-format.md</Path>`。
+
+`CONTEXT.md` 应该完全不包含实现细节。不要将 `CONTEXT.md` 当作规范、草稿纸或实现决策的仓库。它只是词汇表，别无其他。
+
+- **新增术语**：在合适的子标题下追加条目。
+- **修改术语**：直接更新定义文本和 `_Avoid_` 列表。
+- **删除术语**：移除整个条目。
+- **术语更名**：删除旧条目，新增新条目。
+
+## 谨慎更新 ADR.md
+
+仅在以下三个条件全部满足时才向 `ADR.md` 追加一条决策记录：
+
+1. **难以逆转**——以后改变主意的成本是有意义的
+2. **没有上下文会令人惊讶**——未来的读者会疑惑"他们为什么这样做？"
+3. **真实权衡的结果**——存在真正的替代方案，你出于特定原因选择了一个
+
+如果缺少任何一个条件，跳过 ADR。具体格式参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/adr-format.md</Path>`。
+
+`ADR.md` 中每个决策是一个 `## NNNN: {标题}` 二级标题，编号顺序递增，条目之间用 `---` 分隔。可以修改已有条目、标记废弃——但不要删除。
+
+## 什么算 ADR
+
+- **架构形态。** "我们使用 monorepo。" "写模型采用事件溯源，读模型投影到 Postgres。"
+- **上下文间的集成模式。** "Ordering 和 Billing 通过领域事件通信，而非同步 HTTP。"
+- **带来锁定效应的技术选择。** 数据库、消息总线、认证提供商、部署目标。不是每个库——只是那些需要花一个季度才能替换的。
+- **边界和范围决策。** "客户数据由 Customer 上下文拥有；其他上下文仅通过 ID 引用它。"明确的"不做"和"要做"同样有价值。
+- **有意偏离显而易见路径的决策。** "我们使用手动 SQL 而不是 ORM，因为 X。"任何合理读者会假设相反的情况。
+- **代码中不可见的约束。** "由于合规要求，我们不能使用 AWS。" "由于合作伙伴 API 合同，响应时间必须低于 200ms。"
+- **拒绝的原因不明显的被拒绝替代方案。** 如果你考虑了 GraphQL 而因微妙原因选择了 REST，记录下来——否则 6 个月后有人会再次建议 GraphQL。
+
+## 三文件同步规则
+
+访谈中每完成一轮设计问答，按以下顺序同步三个文件：
+
+1. **LOG.md** 先更新——立即追加日志条目，记录本次讨论的结论
+2. **CONTEXT.md** 随后更新——从日志中提取新术语或修正的术语定义
+3. **ADR.md** 最后更新——检查是否需要满足三条件追加 ADC（架构决策记录）
+
+如果 CONTEXT 或 ADR 的更新来自日志条目，在日志中补充 `Related: ADR-XXXX` 的关联标注。

package/template/workflows/specdev/G-grill-with-docs/grilling-protocol.md

@@ -0,0 +1,54 @@
+# 访谈协议
+
+请对我进行无情的面试，深入探讨该方案的每一个方面，直到我们达成共识。沿设计树的每个分支逐步推进，逐个解决决策之间的依赖关系。每个问题都给出你的推荐答案。
+
+## 核心规则
+
+### 一次只问一个问题
+
+等待我对每个问题给出反馈后再继续。一次问多个问题会让人困惑，也会让讨论失去焦点。每个问题的回答会自然引出下一个分支的追问，不要跳跃。
+
+### 每个问题给出推荐答案
+
+不要只抛出问题。基于你的分析，给出你认为最好的答案，并解释为什么。然后让我确认、反驳或修正。推荐答案让讨论有锚点——我可以直接同意、微调、或推翻重来，而不是从白纸开始。
+
+### 事实自己查，决策问用户
+
+如果某个*事实*可以通过探索代码库找到，请自行查找，不要来问我。包括：现有实现方式、类型定义、数据流、命名约定、文件结构。但*决策*由我来做——将每个决策提交给我并等待我的回答。事实和决策的边界：事实是关于"现在是什么"，决策是关于"应该是什么"。
+
+### 沿设计树逐分支推进
+
+不要跳跃。如果一个决策依赖另一个决策，先解决被依赖的那个。识别出依赖关系并告诉我："我们需要先决定 X，因为 Y 的选择取决于 X 的结论。"设计树的典型分支顺序：
+
+1. **核心概念** — 领域的实体、值对象、聚合根是什么？
+2. **边界与关系** — 概念之间的边界在哪里？它们如何关联？
+3. **行为与规则** — 每个概念能做什么？有什么约束？
+4. **实现映射** — 概念如何映射到代码结构、数据模型、接口？
+5. **边界场景** — 极端情况和异常如何处理？
+
+### 共识之前不执行
+
+在我确认我们已达成共识之前，不要执行该方案。即使讨论看起来已经穷尽，也要明确询问："我们是否已就该设计达成共识？"只有在得到肯定回答后才进入下一阶段。
+
+## 访谈中维护 LOG.md
+
+在访谈过程中，每当一个结论被确认、延后或被替代时，当场更新 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。不要等访谈结束再批量写入——发生时立即捕获。具体格式参见 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`。
+
+写入 LOG.md 的时机：
+
+- **结论被确认** — 用户明确同意某个设计决定时，立即追加一条 `accepted` 日志
+- **决定被延后** — 用户说"先不定"或"后面再讨论"时，追加一条 `deferred` 日志，记录为什么暂不决定以及从什么角度恢复讨论
+- **结论被替代** — 后续讨论推翻了之前的决定时，将原条目状态改为 `superseded`，标注 `Superseded by: LOG-XXXX`，再新建替代条目
+
+## 访谈节奏
+
+- **开场**：先理解用户想打磨的方案是什么。问清楚范围和目标，然后开始沿设计树推进。
+- **推进**：每个回答后，识别下一个最关键的未解决问题。优先解决会阻塞其他决策的问题。
+- **收束**：当设计树的主要分支都已遍历、且用户确认共识时，访谈结束。不要无限追问无关细节。
+
+## 好的访谈问题范例
+
+- "你把 X 称为 'account'——你指的是 Customer 还是 User？它们在代码中是不同的概念。我建议用 Customer，因为它更精确地描述了购买关系。"
+- "你提到订单可以部分取消。未取消的商品怎么办——它们还能发货吗？我建议将它们标记为可发货状态，因为取消是针对商品行而非整个订单。"
+- "你打算用事件溯源还是 CRUD？考虑到审计需求，我推荐事件溯源——虽然写路径更复杂，但天然支持完整审计日志。"
+- "Ordering 和 Billing 之间你选择了同步 HTTP 调用。这意味着 Billing 挂了订单也创建不了。你确定要这种耦合？我建议用异步领域事件——订单创建后发出事件，Billing 异步消费。"