@namewta/speculo 0.3.0 → 0.3.2

package/template/workflows/specdev/E-engineering-cognitive-mentor/evidence-and-options.md

@@ -0,0 +1,132 @@
+# 证据、Why 与方案比较协议
+
+## 1. 证据等级
+
+### 事实
+
+材料直接支持的陈述。来源优先级按场景选择：
+
+1. 用户最新明确决定；
+2. 当前权威 SpecDev 工件；
+3. 可定位的源码、配置、测试、日志或运行证据；
+4. 官方文档、标准或原始研究；
+5. 高质量二手资料；
+6. 通用工程经验。
+
+通用经验不能替代具体项目事实。
+
+### 推断
+
+由一个或多个事实推导。必须说明推导链和可能的替代解释。
+
+### 假设
+
+尚未确认的可能机制。必须说明：支持证据、反证条件、需要的验证材料和未验证带来的影响。本 Work 不自行运行实验。
+
+### 待验证
+
+当前材料不足。不要用模糊语言掩盖未知；写清缺少什么以及谁或哪个 Work 可以补齐。
+
+### 决策
+
+用户已确认的取舍。决策必须包含原因、约束、后果、反转条件和替代关系。高影响决策摘要同步全局 LOG，并交给真正拥有权威的工件正式化。
+
+### 风险
+
+可能让结论、方案或迁移失败的条件。区分已观察风险与理论风险。
+
+## 2. 来源写法
+
+项目文件、目录和代码位置：
+
+- `<Path>src/example.ts</Path>`
+- `<Path>packages/example/**</Path>`
+
+SpecDev 工件：
+
+- `<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+
+外部来源：
+
+- `<Url>https://example.com/reference</Url>`
+
+行号仅作导航，不作为长期契约。源码结论尽量同时记录文件、类、函数、配置键或测试名称。
+
+## 3. 版本锚点
+
+研究现代库、框架、标准或开源项目时记录：
+
+- 仓库与分支；
+- Tag 或 Commit；
+- 软件版本；
+- 文档版本或发布日期；
+- 查询日期；
+- 环境差异。
+
+无法固定时把版本漂移列为风险，不将“当前”写成永久事实。
+
+## 4. Why 因果链
+
+每个关键解释优先覆盖：
+
+1. **背景：**要解决的约束或问题；
+2. **机制：**系统具体如何运作；
+3. **结果：**机制为何产生当前行为；
+4. **设计原因：**为什么放在这一层、使用这一接口或采用这一模式；
+5. **代价：**复杂度、性能、认知、运维或锁定成本；
+6. **边界：**何时该解释不再成立；
+7. **替代：**其他设计会如何改变结果。
+
+不要只逐行翻译代码、重复文档定义或堆砌术语。
+
+## 5. 候选方案最低集合
+
+存在真实选择时，至少考虑：
+
+- 保持现状；
+- 最小改变方案；
+- 一个具有实质差异的替代方案。
+
+若保持现状明显不安全，仍说明“不做”的后果，而不是假装它不存在。
+
+## 6. 技术与架构比较维度
+
+按场景选择，不机械填满：
+
+| 维度 | 关键问题 |
+|---|---|
+| 需求适配 | 是否直接满足核心行为与非目标？ |
+| 正确性 | 一致性、幂等、顺序、权限和错误语义是否可靠？ |
+| 复杂度 | 实现、理解、调试和维护成本是多少？ |
+| 性能 | 延迟、吞吐、资源和容量上限如何？ |
+| 可靠性 | 故障隔离、恢复、重试、降级和事故半径如何？ |
+| 安全与合规 | 身份、授权、隐私、审计和法规影响是什么？ |
+| 可测试性 | 稳定验证接缝和失败可观察性如何？ |
+| 可观测性 | 日志、指标、追踪和诊断成本如何？ |
+| 团队适配 | 技能、值班、运维和组织边界是否匹配？ |
+| 生态与锁定 | 社区、供应商、协议、迁移出口如何？ |
+| 成本 | 开发、运行、许可和机会成本如何？ |
+| 演进 | 兼容、迁移、回滚和替换路径是否清楚？ |
+
+## 7. 推荐表达
+
+推荐采用条件式结构：
+
+```text
+在 <当前约束> 下，推荐 <方案>，因为 <关键证据与取舍>。
+不选 <替代方案> 的主要原因是 <不匹配项>。
+如果 <反转条件> 发生，推荐应改为 <另一方案>。
+当前仍依赖 <待验证假设>。
+```
+
+不得：
+
+- 编造精确权重或分数；
+- 用流行度代替适配性；
+- 用“最佳实践”掩盖约束差异；
+- 只列优点，不说代价；
+- 给出无法回滚的建议却不说明迁移风险。
+
+## 8. 外部研究
+
+外部事实不清楚时可使用 `<Path>{roots.workflows}/specdev/common/skills/research/SKILL.md</Path>`。研究结果先写入当前主产物并标明查询日期；只有经确认、长期稳定且有明确归属的知识，才在归档阶段提升到永久 research namespace。

package/template/workflows/specdev/E-engineering-cognitive-mentor/interaction-protocol.md

@@ -0,0 +1,116 @@
+# 交互与教学协议
+
+本协议控制提问、解释、理解确认和详细 MLOG。目标是帮助用户形成可复述的工程判断，而不是用问题拖延答案。
+
+## 1. 先发现，后询问
+
+先读取可访问的项目事实、已有工件和外部权威资料。以下内容不得转交给用户人工查找：
+
+- 仓库中可直接确认的文件、配置、接口和测试；
+- 已有 Spec、ADR、诊断、Ticket 和日志中的明确决定；
+- 官方文档可直接确认的版本行为；
+- 前文已经回答的事实。
+
+只询问：业务偏好、风险承受度、互斥目标、缺失的环境事实、用户真正想达成的结果，以及无法从材料发现但会改变结论的事项。
+
+## 2. 建立用户当前模型
+
+从用户表述提取：
+
+- 已知事实；
+- 用户自己的解释或倾向；
+- 不确定点；
+- 可能存在的误解；
+- 希望获得的深度；
+- 是否希望快速结论、系统教学或决策支持。
+
+不要求用户先完成“自我分析”才提供帮助。用户没有初步判断时，直接给出必要地图和条件式结论。
+
+## 3. 每轮结构
+
+每轮处理一个相对完整的问题簇：
+
+1. **当前回答：**先回应用户刚才的问题；
+2. **证据状态：**简洁区分事实、推断、假设和待验证；
+3. **Why：**解释机制、原因、影响和边界；
+4. **方案取舍：**存在真实选择时才给；
+5. **唯一问题：**只有会改变下一步结论时才询问；
+6. **落盘：**追加 MLOG 并更新综合。
+
+用户要求“直接告诉我”时，先给答案。教学协议不得成为扣留结论的理由。
+
+## 4. 提问质量
+
+高价值问题必须满足：
+
+- 一次只问一个决策维度；
+- 用户回答会实际改变解释、推荐、风险或范围；
+- 不把多个独立问题塞进一个句子；
+- 提供必要背景和可行选项；
+- 默认给出推荐及原因，除非证据不足；
+- 不问抽象的“你想要什么风格”式问题。
+
+低价值问题包括：可从仓库发现、只为填模板、不会改变结论、重复已答内容或要求用户搬运大量材料。
+
+## 5. 纠错方式
+
+发现用户理解可能错误时：
+
+1. 先承认其中正确部分；
+2. 指出与证据冲突的具体命题；
+3. 解释导致误解的直觉来源；
+4. 给出更准确的因果模型；
+5. 说明该修正会改变什么判断；
+6. 在 MLOG 记录“旧理解 → 新理解”，而不是隐藏变化。
+
+AI 自己的旧结论被新证据推翻时同样处理，并明确承认。
+
+## 6. MLOG 格式
+
+详细日志位于主产物的“完整交互日志”章节，只追加不覆盖：
+
+```markdown
+## MLOG-### — <ISO-8601> — <模式>/<阶段> — <主题>
+
+- **状态：** answered / confirmed / deferred / rejected / superseded / blocked
+- **用户输入摘要：**
+- **用户当前理解：**
+- **导师回答：**
+- **导师唯一问题：** 无 / ...
+- **用户回答：** 无 / ...
+- **新增事实与来源：**
+- **新增推断或假设：**
+- **Why 因果链：**
+- **候选方案与取舍：** 不适用 / ...
+- **推荐与反转条件：** 不适用 / ...
+- **决定或理解变化：**
+- **未决问题：**
+- **影响工件：** mentor-report / LOG / ADR / CONTEXT / Spec / Ticket / 无
+- **关联全局 LOG：** LOG-### / 无
+- **替代/被替代：** MLOG-### / 无
+- **下一焦点：**
+```
+
+“用户输入摘要”保存语义，不逐字复制敏感或冗长内容。需要保留原文时使用来源指针。
+
+## 7. 轮次原子性
+
+一条 MLOG 对应一次有实质信息变化的用户—导师交互。以下情况不新建：
+
+- 用户仅表示收到；
+- 内容完全重复且没有新决定；
+- 系统重试导致同一回合再次执行。
+
+若导师问题在上一轮提出、用户本轮回答，可以在新 MLOG 中引用上一条编号，不回写旧条目。
+
+## 8. 不布置实践任务
+
+本 Work 不要求用户：
+
+- 写代码；
+- 修改文件；
+- 运行测试或命令；
+- 完成练习、作业或挑战；
+- 通过实践题才获得后续解释。
+
+可以提供“将来可如何验证”的建议，但必须标记为未执行、非作业，并说明验证目的。

package/template/workflows/specdev/E-engineering-cognitive-mentor/mentor-report-template.md

@@ -0,0 +1,135 @@
+---
+schema_version: 1
+artifact: engineering-cognitive-mentor
+change: <YYYY-MM-DD-topic>
+status: active
+primary_mode: null
+secondary_modes: []
+current_phase: intake
+understanding_status: unverified
+started_at: <ISO-8601>
+updated_at: <ISO-8601>
+closed_at: null
+last_mlog_id: null
+next_question: null
+---
+
+# 工程认知导师记录：<主题>
+
+> **工件职责：** 本文是当前 change 的工程认知综合、详细问答轨迹与恢复入口。产品行为以 Spec 为权威，架构决定以 ADR 为权威，执行契约以 Ticket 为权威。本文不得覆盖这些工件。
+
+## 1. 会话与研究契约
+
+- **用户目标：**
+- **期望输出：**
+- **成功标准：**
+- **研究范围：**
+- **不处理范围：**
+- **主模式：**
+- **次模式与顺序：**
+- **版本/分支/Commit/查询日期：**
+- **关键约束：**
+- **权威输入：**
+
+## 2. 用户当前认知模型
+
+### 已经知道
+
+### 当前判断或倾向
+
+### 困惑与不确定点
+
+### 已纠正的误解
+
+## 3. 执行摘要
+
+> 持续更新当前最可靠的总结。历史变化保留在 MLOG，不在本节复制全部讨论。
+
+## 4. 全局地图与主链路
+
+### 全貌
+
+### 主链路
+
+### 关键边界
+
+## 5. 事实、推断、假设与待验证
+
+| ID | 类型 | 陈述 | 来源或推导 | 状态/影响 |
+|---|---|---|---|---|
+
+## 6. 核心机制与 Why
+
+### 背景与约束
+
+### 机制
+
+### 结果与影响
+
+### 设计原因
+
+### 代价与边界
+
+## 7. 候选方案与技术栈比较
+
+| 方案 | 核心思路 | 适用约束 | 优点 | 代价/风险 | 迁移与回滚 | 反转条件 |
+|---|---|---|---|---|---|---|
+
+### 当前推荐
+
+### 不选其他方案的原因
+
+### 仍依赖的假设
+
+## 8. 模式专项分析
+
+> 根据 Bug、源码、需求、架构或新领域模式填写。不适用内容写“不适用”。
+
+## 9. 已确认决定与理解变化
+
+| ID | 类型 | 结论 | 原因 | 来源 | 替代关系 | 影响工件 |
+|---|---|---|---|---|---|---|
+
+## 10. 未决问题与待验证项
+
+| ID | 问题 | 为什么重要 | 所需信息/证据 | 是否阻塞 | 建议归属 |
+|---|---|---|---|---|---|
+
+## 11. 理解确认
+
+- **状态：** unverified
+- **导师最终总结：**
+- **用户复述或确认：**
+- **仍不清楚/不同意：**
+- **是否还有其他问题：**
+
+## 12. 后续路线与移交
+
+- **下一焦点：**
+- **下一 Work：** 无
+- **移交原因：**
+- **恢复说明：**
+
+## 13. 完整交互日志
+
+> MLOG 只追加不覆盖。结论变化时新增条目并引用旧编号。
+
+## MLOG-001 — <ISO-8601> — <模式>/<阶段> — 初始化
+
+- **状态：** answered
+- **用户输入摘要：**
+- **用户当前理解：**
+- **导师回答：**
+- **导师唯一问题：** 无
+- **用户回答：** 无
+- **新增事实与来源：**
+- **新增推断或假设：**
+- **Why 因果链：**
+- **候选方案与取舍：** 不适用
+- **推荐与反转条件：** 不适用
+- **决定或理解变化：**
+- **未决问题：**
+- **影响工件：** mentor-report
+- **关联全局 LOG：** 无
+- **替代/被替代：** 无
+- **下一焦点：**

package/template/workflows/specdev/E-engineering-cognitive-mentor/mode-routing.md

@@ -0,0 +1,47 @@
+# 场景路由协议
+
+选择主模式的目标是控制上下文和分析顺序，不是把复杂请求强行归为单一类别。
+
+## 1. 主模式判定
+
+| 模式 | 典型信号 | 主要输出 |
+|---|---|---|
+| `bug` | 报错、异常、错误结果、性能退化、事故、根因 | 现象—机制—证据—根因候选—修复原则的认知地图 |
+| `codebase` | 仓库、源码、模块、启动流程、调用链、开源项目 | 项目全貌、架构、入口、核心链路、关键代码与阅读地图 |
+| `requirements` | 需求、业务流程、技术方案、技术选型、可行性 | 问题定义、约束、候选方案、推荐与反转条件 |
+| `architecture` | 系统边界、架构设计、高可用、扩展性、一致性、评审 | 驱动因素、结构与数据流、质量属性、故障模型和架构取舍 |
+| `domain-learning` | 陌生概念、新技术、新行业、原理学习、技术地图 | 知识地图、核心机制、术语关系、技术生态与常见误区 |
+
+## 2. 混合模式
+
+混合请求先识别“当前阻止用户继续判断的主要未知”。按依赖顺序处理，例如：
+
+- Bug + 源码：先建立最短故障链，再补相关模块结构；
+- 需求 + 架构：先明确业务目标与质量属性，再比较架构；
+- 新领域 + 技术选型：先建立概念和约束，再做产品或技术比较；
+- 源码 + 二次开发方案：先理解现有扩展点，再讨论方案；
+- 架构 + Bug：若事故正在发生，先解释故障机制；若是长期治理，先明确架构压力。
+
+在主产物记录：
+
+- `primary_mode`；
+- `secondary_modes`；
+- `mode_order`；
+- 每个模式的进入条件与退出条件。
+
+## 3. 不应由本 Work 独立承担的情况
+
+- 必须运行实验、测试或插桩才能继续定位：移交 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
+- 调查面过大、需多 Agent 或并行领取未知项：移交 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
+- 需要正式锁定产品行为和验收：移交 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
+- 需要正式架构候选接受与 ADR 同步：移交 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>` 或 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
+- 用户要求实施、修复或提交：本 Work 先完成解释与边界说明，再按治理路线移交，不自行执行。
+
+## 4. 路由变更
+
+新证据改变主问题时可以切换模式，但必须：
+
+1. 在 MLOG 记录旧模式为何不足；
+2. 标记旧结论仍有效、被限制或被替代的部分；
+3. 更新 frontmatter 的模式与阶段；
+4. 不重复加载无关专项协议。

package/template/workflows/specdev/E-engineering-cognitive-mentor/persistence-and-resume.md

@@ -0,0 +1,147 @@
+# 持久化与恢复协议
+
+本协议是工程认知导师 Work 的状态与落盘权威。它细化 Speculo 全局持久化契约，不改变其他 Work 的工件职责。
+
+## 1. 根与 change 解析
+
+1. 从当前工作目录向上寻找唯一的 Speculo 工作区声明（`.speculo` 下的 workspace 配置）；
+2. 第一个唯一命中的目录为 project root；多个候选或用户指定目录冲突时停止并消歧；
+3. `path_base` 必须为 `project-root`；
+4. 读取 roots 后，将 Work 路径解析为 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/</Path>`，状态路径解析为 `<Path>{roots.state}/specdev/</Path>`；
+5. 用户指定 change 优先；否则唯一 active change 直接使用；没有 active change 时按 `YYYY-MM-DD-<kebab-topic>` 创建；多个 active change 不得猜测。
+
+若 `<Path>{roots.state}/specdev/config.json</Path>` 不存在，先进入 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`。
+
+## 2. 状态文件
+
+全局状态：`<Path>{roots.state}/specdev/status.json</Path>`。
+
+change 状态：`<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`。
+
+主产物：`<Path>{roots.state}/specdev/changes/{change}/engineering-cognitive-mentor.md</Path>`。
+
+跨 Work 决策日志：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`。
+
+### 开始
+
+- 在 `active` 中找到或创建当前 change；
+- 设置该 change 的 `current_work` 为 `specdev/engineering-cognitive-mentor`；
+- `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `current_work` 同步设置为相同值；
+- 在 `work_history` 中查找该 change 与 work id 的未完成记录；存在唯一一条时复用，不重复创建；不存在时追加：
+
+```json
+{
+  "change": "<change>",
+  "work_id": "specdev/engineering-cognitive-mentor",
+  "started_at": "<ISO-8601>",
+  "completed_at": null,
+  "result": null
+}
+```
+
+若存在两条以上未完成记录，记录状态异常并停止自动写入，先请求消歧或修复。
+
+### 等待用户或跨会话暂停
+
+- 保持 `current_work` 为本 Work；
+- 保持唯一 `work_history` 记录未完成；
+- 更新主产物 `updated_at`、`current_phase`、`next_question`、`unresolved_questions` 与 `last_mlog_id`；
+- 每轮在回复前先落盘，确保用户即使中断也可恢复。
+
+等待用户回答不是 blocked，不应把 change 标为 blocked。
+
+### 正常关闭
+
+- 将唯一未完成 `work_history` 的 `completed_at` 写为当前时间，`result` 写为 `completed`；
+- 将本 Work id 以去重方式加入 active change 的 `works_run`；
+- active change 的 `current_work` 与 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `current_work` 设为 null；
+- 不改变整个 change 的 `result` 或 `change_status`，除非用户明确结束、取消或外部阻塞确实影响整个 change；
+- 主产物 `status` 写为 `completed`，记录 `closed_at` 与理解确认状态。
+
+### 外部阻塞
+
+只有缺少权限、不可访问资料、必须等待第三方结果或存在互斥权威冲突时才标 blocked：
+
+- 主产物 `status: blocked`；
+- 记录 blocker、已知事实、所需输入和恢复条件；
+- 完成当前 `work_history`，结果为 `blocked`；
+- change 是否设为 blocked 取决于该阻塞是否阻止整个 change，不自动扩大。
+
+### 用户取消
+
+- 主产物 `status: cancelled`；
+- 保存当前综合和完整 MLOG；
+- `work_history.result` 写为 `cancelled`；
+- 清空 current_work；
+- 不删除工件或日志。
+
+## 3. 主产物幂等初始化
+
+主产物不存在时，使用 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/mentor-report-template.md</Path>` 创建。
+
+主产物已存在时：
+
+- 不重新生成或覆盖；
+- 读取 frontmatter、当前综合、未决问题和最后一个 `MLOG`；
+- 可补齐缺失的可选章节，但不得重排或改写历史日志；
+- 未识别的新字段原样保留；
+- schema version 1 缺失可选字段时按空值读取，在真实更新时补齐。
+
+## 4. 每轮落盘顺序
+
+每次有实质交互时按以下顺序写入：
+
+1. 追加新的 `MLOG-###`；
+2. 更新主产物的当前综合、证据表、方案表和未决问题；
+3. 若有高影响决定，摘要追加全局 `LOG-###`；
+4. 更新主产物 frontmatter 的阶段、状态、理解状态、时间和最后日志编号；
+5. 更新 `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>` 的 `updated_at`；
+6. 返回用户回复。
+
+写入中断时，以已追加的 MLOG 为恢复锚点；不得为同一用户回合重复追加。可以用时间、上一条 MLOG 和用户输入摘要检测重复。
+
+## 5. MLOG 与全局 LOG 的职责
+
+### MLOG：详细、Work 专属
+
+主产物中的 MLOG 保存：用户问题摘要、导师问题、用户回答、解释、证据变化、误解修正、方案比较、理解确认和下一焦点。
+
+### 全局 LOG：高影响、跨 Work
+
+只有满足以下任一条件才追加到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`：
+
+- 用户确认或拒绝会改变产品行为、范围、验收、架构边界、迁移、安全或重大风险的选择；
+- 某项结论阻止或允许进入 Spec、Ticket、Goal Plan 或 Implement；
+- 先前跨 Work 决策被替代；
+- 需要其他 Work 恢复时必须知道的阻塞或 handoff。
+
+全局 LOG 条目使用 `<Path>{roots.workflows}/specdev/G-grill-with-docs/log-format.md</Path>`，并在“事实与来源”或“后续”中引用对应 `MLOG-###` 与主产物完整路径。
+
+普通教学解释、低影响偏好和用户的每个追问不得复制到全局 LOG。
+
+## 6. 恢复读取顺序
+
+跨会话恢复时按顺序读取：
+
+1. `<Path>{roots.state}/specdev/status.json</Path>`；
+2. `<Path>{roots.state}/specdev/changes/{change}/.status.json</Path>`；
+3. `<Path>{roots.state}/specdev/changes/{change}/engineering-cognitive-mentor.md</Path>`；
+4. 其中列出的权威输入与外部引用；
+5. `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>` 中与 MLOG 关联的高影响条目；
+6. 按当前模式加载所需专项协议。
+
+恢复后先向用户简短说明：当前模式、已确认结论、未决问题和下一焦点。不要重新复述全文或重新询问已回答问题。
+
+## 7. 工件冲突
+
+冲突按 `<Path>{roots.workflows}/specdev/common/rules/artifact-contract.md</Path>` 裁决。
+
+- 用户最新明确决定优先；
+- 主产物是教学综合与详细 MLOG 的权威，不是产品行为或架构决定的最终权威；
+- 若主产物与 ADR、Spec 或 Ticket 冲突，指出冲突并移交真正拥有该决定的 Work 修订；
+- 代码事实可以证明旧解释过时，但不能静默改写用户目标；
+- 所有替代通过新 MLOG 和必要的全局 LOG 记录，不删除旧内容。
+
+## 8. 敏感信息
+
+不得将令牌、密码、密钥、完整个人数据、内部凭证、生产连接串或未脱敏客户数据写入 Speculo 状态。日志只保存脱敏摘要和安全的来源指针。

package/template/workflows/specdev/E-engineering-cognitive-mentor/requirements-guidance.md

@@ -0,0 +1,92 @@
+# 需求与技术方案指导
+
+本模式把“想要一个功能”还原为用户问题、行为合同、约束和可解释的技术选择。它不直接创建权威 Spec 或 Ticket。
+
+## 1. 问题定义
+
+区分：
+
+- 用户或业务问题；
+- 期望结果；
+- 请求中的具体功能想法；
+- 成功指标；
+- 明确非目标；
+- 当前流程和痛点；
+- 谁受影响、谁批准、谁运维。
+
+功能想法不是天然的需求结论。
+
+## 2. 行为与约束地图
+
+梳理：
+
+- 参与者与权限；
+- 主要用户流程；
+- 输入、输出、状态和业务规则；
+- 正常、异常和边界场景；
+- 数据、不变量和生命周期；
+- 兼容、迁移和发布限制；
+- 性能、可靠性、安全、隐私、审计、成本和时间约束；
+- 可观察成功状态。
+
+## 3. 关键未知项
+
+分为：
+
+- 可从现有项目发现的事实；
+- 需要用户做业务取舍的 decision-needed；
+- 需要外部研究的技术事实；
+- 可延后到 Ticket 或实现阶段的低影响细节。
+
+只询问前两类中真正会改变方案的事项。
+
+## 4. 方案形成
+
+每个方案说明：
+
+- 核心思路；
+- 满足哪些行为和约束；
+- 依赖的假设；
+- 数据和接口影响；
+- 失败模式；
+- 实施与认知复杂度；
+- 兼容、迁移和回滚；
+- 可观测性与运维；
+- 长期演进；
+- 不适用条件。
+
+至少比较保持现状、最小方案和一个实质替代方案。
+
+## 5. 技术栈比较
+
+先比较“能力和约束”，再比较具体产品。避免仅按流行度、性能榜或个人偏好选择。
+
+示例层级：
+
+```text
+需求约束
+  → 架构能力（同步/异步、事务/最终一致、托管/自建）
+  → 技术类别（关系库、消息系统、缓存、工作流引擎）
+  → 具体产品与版本
+```
+
+若具体产品信息可能变化，必须查当前官方资料并记录查询日期。
+
+## 6. 推荐与决策支持
+
+推荐说明：
+
+- 当前最关键的 2–4 个决策驱动因素；
+- 推荐方案如何满足它们；
+- 被拒方案在哪些约束上不匹配；
+- 反转条件；
+- 未验证假设；
+- 需要正式写入 Spec 或 ADR 的事项。
+
+## 7. 移交
+
+- 需求和行为仍不清：`<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
+- 外部行为、范围和验收已清楚：`<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
+- 方案已锁定且需要执行切片：`<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`。
+
+主产物保留解释与讨论历史，但不冒充上述权威工件。