@namewta/speculo 0.2.3 → 0.2.7

package/template/workflows/person/INDEX.md

@@ -0,0 +1,12 @@
+---
+id: person/index
+type: workflow-index
+workflow: person
+auto_generated: true
+---
+
+# person — Work Index
+
+> 本文件由 `generate-index.mjs` 自动生成，**禁止手动编辑**。
+
+- **M-mao-zedong-cognitive-os** — 毛泽东认知操作系统：以毛泽东方法论为底座的问题诊断、战略制定与行动规划咨询

package/template/workflows/person/M-mao-zedong-cognitive-os/M-mao-zedong-cognitive-os.md

@@ -9,81 +9,80 @@ keywords: [毛泽东, 毛选, 矛盾分析, 战略, 组织, 咨询]
 
 # 毛泽东 · 认知操作系统
 
-本入口把“分析问题—制定战略—组织行动”组织为渐进披露的咨询流程。产物写入当前 `person/changes/<change>/`。
-
-## 阶段
-
-```xml
-<sequence>
-  <phase id="activate" order="1">
-    <instructions root="workflow" path="M-mao-zedong-cognitive-os/activate.md" />
-    <artifact root="change" path="problem-statement.md" />
-    <completion>首次激活声明已执行，问题陈述无 TODO。</completion>
-  </phase>
-  <phase id="diagnose" order="2">
-    <instructions root="workflow" path="M-mao-zedong-cognitive-os/diagnose.md" />
-    <artifact root="change" path="analysis.md" />
-    <completion>至少两个诊断模型已应用，分析无 TODO。</completion>
-  </phase>
-  <phase id="strategize" order="3">
-    <instructions root="workflow" path="M-mao-zedong-cognitive-os/strategize.md" />
-    <artifact root="change" path="strategy.md" />
-    <completion>主要矛盾和战略框架已确认。</completion>
-  </phase>
-  <phase id="mobilize" order="4">
-    <instructions root="workflow" path="M-mao-zedong-cognitive-os/mobilize.md" />
-    <artifact root="change" path="action-plan.md" />
-    <completion>行动、责任与反馈机制已明确。</completion>
-  </phase>
-  <phase id="deliver" order="5">
-    <instructions root="workflow" path="M-mao-zedong-cognitive-os/deliver.md" />
-    <template root="workflow" path="_templates/mao-consultation-output-template.md" />
-    <artifact root="change" path="consultation-output.md" />
-    <completion>综合输出无 TODO，并经用户确认。</completion>
-  </phase>
-</sequence>
-```
-
-## 依赖
-
-```xml
-<dependencies>
-  <dependency kind="hard" from="diagnose" to="activate" />
-  <dependency kind="hard" from="strategize" to="diagnose" />
-  <dependency kind="hard" from="mobilize" to="strategize" />
-  <dependency kind="hard" from="deliver" to="mobilize" />
-</dependencies>
-```
-
-## 状态扩展字段
-
-```xml
-<state-schema>
-  <field name="problem_type" type="string" />
-  <field name="primary_framework" type="string" />
-  <field name="models_applied" type="array" />
-  <field name="frameworks_applied" type="array" />
-  <field name="methods_applied" type="array" />
-  <field name="quotes_cited" type="array" />
-  <field name="consultation_status" type="activating|diagnosing|strategizing|mobilizing|delivering|completed" />
-</state-schema>
-```
-
-## 状态转移
-
-```xml
-<transitions>
-  <transition from="activate" to="diagnose" />
-  <transition from="diagnose" to="strategize" />
-  <transition from="strategize" to="mobilize" />
-  <transition from="mobilize" to="deliver" />
-  <transition from="deliver" to="finalize">
-    <command root="commands" path="finalize.md" />
-    <when>用户确认综合咨询输出。</when>
-  </transition>
-</transitions>
-```
+本入口把"分析问题—制定战略—组织行动"组织为渐进披露的咨询流程。产物写入当前 `person/changes/<change>/`。
+
+## 流程
+
+### 1. 激活与问诊
+
+委托给 `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/activate.md</Path>`。输出首次激活声明，通过开口三问摸清用户处境，判定问题类型并匹配主框架。
+
+产物：`<Path>{roots.state}/person/changes/{change}/problem-statement.md</Path>`
+
+**完成标准**：首次激活声明已输出，至少已追问 2 个开口问题且用户已回应，问题类型与主框架已匹配，problem-statement.md 六段均已填写无残留 `[TODO:]`。
+
+### 2. 诊断分析
+
+依赖步骤 1 的 problem-statement.md。委托给 `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/diagnose.md</Path>`。从 Module A 八模型中选用至少 2 个进行诊断——所有问题必过 A1（矛盾分析）；信息来自二手必过 A3（调查研究）；涉及多方利益必过 A6（结构分析）。
+
+产物：`<Path>{roots.state}/person/changes/{change}/analysis.md</Path>`
+
+**完成标准**：已应用至少 2 个 Module A 模型，每个模型结论带条件与局限，主要矛盾已明确写出且带论证，analysis.md 无残留 `[TODO:]`。
+
+### 3. 战略制定
+
+依赖步骤 2 的 analysis.md。委托给 `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/strategize.md</Path>`。沿元框架流水线（定性→定向→站位→时间→投放→运用）展开主框架，必要时补充辅助框架。
+
+产物：`<Path>{roots.state}/person/changes/{change}/strategy.md</Path>`
+
+**完成标准**：主框架已选定并充分展开，阶段划分清晰（至少分两步），有明确的关键战役判断，strategy.md 无残留 `[TODO:]`。
+
+### 4. 组织行动
+
+依赖步骤 3 的 strategy.md。委托给 `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/mobilize.md</Path>`。将战略转化为具体行动方案——谁来干、干什么、什么时候干完、干到什么程度算好、干砸了怎么办。
+
+产物：`<Path>{roots.state}/person/changes/{change}/action-plan.md</Path>`
+
+**完成标准**：行动、责任与反馈机制已明确，action-plan.md 无残留 `[TODO:]`。
+
+### 5. 综合交付
+
+依赖前四步全部产物。委托给 `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/deliver.md</Path>`。按模板 `../_templates/mao-consultation-output-template.md` 整合为连贯的教员第一人称咨询输出——五拍论证节奏、收尾四动作、引用纪律、反模式检查和内在张力标注。
+
+产物：`<Path>{roots.state}/person/changes/{change}/consultation-output.md</Path>`
+
+**完成标准**：已整合四阶段产物为连贯的教员第一人称咨询输出，五拍论证节奏可辨识，收尾四动作齐全，所有毛泽东原文引用均带篇目出处，反模式检查通过，consultation-output.md 无残留 `[TODO:]`。
+
+## 依赖关系
+
+- 步骤 2「诊断分析」依赖步骤 1「激活与问诊」
+- 步骤 3「战略制定」依赖步骤 2「诊断分析」
+- 步骤 4「组织行动」依赖步骤 3「战略制定」
+- 步骤 5「综合交付」依赖步骤 4「组织行动」
+
+所有步骤为硬依赖——前一产物必须完成并验证后才能进入下一步。
+
+## 状态追踪
+
+咨询过程中维护以下状态字段，记录在 `<Path>{roots.state}/person/status.json</Path>` 中：
+
+- **`problem_type`**（字符串）—— 问题类型，从激活阶段的问题类型表中选定
+- **`primary_framework`**（字符串）—— 匹配的主框架及篇目编号
+- **`models_applied`**（数组）—— 诊断阶段已应用的 Module A 模型列表
+- **`frameworks_applied`**（数组）—— 战略阶段已应用的 Module B 框架列表
+- **`methods_applied`**（数组）—— 组织阶段已应用的 Module C 方法列表
+- **`quotes_cited`**（数组）—— 已引用的毛泽东原话及出处
+- **`consultation_status`**（字符串）—— 当前阶段：`activating` → `diagnosing` → `strategizing` → `mobilizing` → `delivering` → `completed`
 
 ## 渐进披露
 
 角色、声音、模型和引用规则继续由各 phase 文件及其相对引用拥有；未进入 phase 时不加载对应材料。
+
+| 文件 | 触发条件 |
+|------|----------|
+| `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/activate.md</Path>` | 步骤 1「激活与问诊」进入时 |
+| `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/diagnose.md</Path>` | 步骤 2「诊断分析」进入时 |
+| `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/strategize.md</Path>` | 步骤 3「战略制定」进入时 |
+| `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/mobilize.md</Path>` | 步骤 4「组织行动」进入时 |
+| `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/deliver.md</Path>` | 步骤 5「综合交付」进入时 |
+| `<Path>{roots.workflows}/person/M-mao-zedong-cognitive-os/books/README.md</Path>` | 需要查原文时——引语库 `references/research/15-quote-bank.md` 映射篇目编号到 books 目录 |

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

@@ -0,0 +1,85 @@
+---
+id: specdev/diagnose-bugs
+type: workflow-entry
+workflow: specdev
+name: 诊断
+description: 针对疑难 bug 建立诊断循环——构建紧凑反馈回路、复现最小化、可证伪假设排名、插桩定位根因，确认后移交 I-implement 修复。
+keywords: [诊断, 调试, bug, 反馈回路, 假设, 根因分析]
+---
+
+# 诊断
+
+针对疑难 bug 的诊断规程。先建立紧凑的反馈回路锚定症状，再通过可证伪假设排名定位根因，确认后移交 I-implement 执行修复。仅在明确有理由时才跳过阶段。
+
+在开始诊断之前，读取当前变更的上下文与架构决策：
+
+- **CONTEXT.md** —— 项目领域术语与概念：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- **ADR.md** —— 架构决策记录：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+
+如果这些文件不存在，先运行 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>` 或询问用户以建立上下文。
+
+## 流程
+
+### 1. 加载上下文
+
+读取 `<Path>{roots.state}/specdev/status.json</Path>` 确认活跃变更。读取 CONTEXT.md 获取领域词汇表——使用其中已定义的术语。读取 ADR.md 了解已做出的架构决策——诊断过程中涉及的模块若与已有 ADR 相关，在假设中引用。
+
+**完成标准**：活跃变更已确认，领域词汇表和架构决策已加载。`{change}` 已确定。
+
+### 2. 构建反馈回路
+
+委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop-techniques.md</Path>`。构建一个紧凑的通过/失败信号——一条命令，确定性、秒级、agent 可无人值守运行。在此投入不成比例的精力：反馈回路是诊断的超能力。如果确实无法构建回路，向用户明确说明已尝试的方法并请求访问复现环境或捕获产物。
+
+**完成标准**：反馈回路紧凑且具备变红能力——一条命令已运行并通过/失败输出验证，确定性、秒级、agent 可运行。回路断言的是用户的确切症状，而非"运行不出错"。
+
+### 3. 复现与最小化
+
+运行回路，确认它产生用户描述的故障模式。然后逐元素削减输入、调用者、配置和数据——每次削减后重新运行回路——只保留对故障有负载作用的部分。
+
+**完成标准**：回路已复现用户症状。复现场景已最小化——每个剩余元素都有负载作用，移除任何一个都会使回路变绿。
+
+### 4. 提出诊断计划
+
+委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-format.md</Path>`。生成 3-5 个排名假设，每个假设必须是可证伪的——陈述其预测。将排名列表作为诊断计划呈现给用户确认。用户可能拥有立即重排名的领域知识。如果用户 AFK，按排名继续。
+
+**完成标准**：3-5 个可证伪假设已排名并作为诊断计划呈现给用户。用户已确认或 AFK 下按排名继续。
+
+### 5. 插桩验证
+
+委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/instrumentation-rules.md</Path>`。每个探测映射到诊断计划中的一个具体预测。每次只改变一个变量。使用调试器/REPL 优先于日志。所有调试日志使用 `[DEBUG-xxxx]` 唯一前缀标记。
+
+**完成标准**：根因已通过插桩确认——某个假设的预测已验证，其他假设已排除。所有探测结果与诊断计划中的预测对应。
+
+### 6. 移交修复
+
+调用 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行修复。移交以下信息：
+
+- **根因描述**——哪个假设被确认，通过什么探测验证
+- **最小复现场景**——阶段 3 产出的最小化复现，可直接转为回归测试
+- **建议的修复接缝**——在哪个模块/接口处修复最合适
+
+修复、回归测试编写和提交由 I-implement 完成。如果不存在正确的测试缝合点，将此发现记录到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 并在步骤 7 的事后分析中提出架构改进建议。
+
+**完成标准**：I-implement 已启动，根因描述、最小复现、建议修复接缝已移交。
+
+### 7. 清理与复盘
+
+委托给 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/cleanup-postmortem.md</Path>`。移除所有 `[DEBUG-xxxx]` 标记的插桩代码，删除一次性原型。在 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 中记录：被证实的假设、根因、修复提交。执行事后分析——什么本可以预防这个 bug？如果涉及架构变更，提出改进建议。
+
+**完成标准**：调试产物已清理（grep `[DEBUG-` 无残留），根因已记录到 LOG.md，预防建议已提出。
+
+---
+
+## 子文件引用
+
+| 文件 | 内容 | 触发条件 |
+|------|------|---------|
+| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/feedback-loop-techniques.md</Path>` | 10 种反馈回路构建技术、收紧回路、非确定性 bug 策略、无法构建回路时的升级路径、最小化协议 | 步骤 2「构建反馈回路」和步骤 3「复现与最小化」进入时 |
+| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/hypothesis-format.md</Path>` | 可证伪假设格式模板、排名规则、用户 Plan 呈现模板、AFK 默认行为 | 步骤 4「提出诊断计划」进入时 |
+| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/instrumentation-rules.md</Path>` | 探测映射规则、工具偏好、`[DEBUG-xxxx]` 标记约定、性能分支处理 | 步骤 5「插桩验证」进入时 |
+| `<Path>{roots.workflows}/specdev/D-diagnose-bugs/cleanup-postmortem.md</Path>` | 清理检查清单、事后分析问题、预防建议记录格式 | 步骤 7「清理与复盘」进入时 |
+
+## 依赖关系
+
+- 依赖 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>` 执行修复——步骤 6 移交已确认的根因和最小复现
+- 依赖 `<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>` 和 `<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>` 提供领域上下文——步骤 1 加载

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。