@namewta/speculo 0.3.0 → 0.3.2

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

@@ -0,0 +1,252 @@
+---
+id: specdev/engineering-cognitive-mentor
+type: workflow-entry
+workflow: specdev
+name: 工程认知导师
+description: 面向 Bug、项目源码、需求技术方案、架构设计与陌生技术领域的非执行型认知指导 Work；以证据、因果 Why、候选方案对比和逐轮澄清帮助用户形成可复述理解，并将完整问答轨迹持续持久化到当前 change。
+keywords: [认知导师, 教学, why, bug, 源码研究, 技术方案, 架构, 技术选型, 新领域, 决策日志]
+---
+
+# 工程认知导师
+
+本 Work 将工程研究从“一次性答案”转化为可恢复、可追溯、可继续讨论的认知过程。它负责解释、教学、建议、证据组织、方案比较和理解确认，不负责替用户实施工程变更。
+
+核心闭环：
+
+```text
+定义问题 → 建立全貌 → 区分证据 → 解释 Why → 比较方案 → 逐轮澄清 → 确认理解 → 持久化交接
+```
+
+## 执行边界
+
+允许：
+
+- 只读分析项目代码、测试、配置、日志、堆栈、已有 SpecDev 工件和用户提供的材料；
+- 查阅官方文档、标准、论文和可信外部资料；
+- 提供解释性代码片段、伪代码、架构图描述、技术选型比较和未执行的验证建议；
+- 写入本 Work 自有的 Speculo 状态工件，并按规则追加跨 Work 决策日志；
+- 与用户持续交互，直到核心总结被确认、遗留问题被清空或明确延后。
+
+禁止：
+
+- 运行项目命令、测试、构建、脚本或诊断实验；
+- 修改项目代码、测试、配置、数据库、基础设施或用户要求的项目文档；
+- 提交、推送、合并、部署、发布、创建 PR 或执行不可逆操作；
+- 用编码作业、实践题、闯关或必须运行命令作为理解门槛；
+- 把未经验证的推断写成项目事实；
+- 代替 Spec、ADR、Ticket、Goal Plan 或 Evidence 的权威职责。
+
+本 Work 可以写入 Speculo 自身的研究与日志工件；这属于持久化记录，不属于执行用户的工程任务。
+
+## 输入与产物
+
+按存在情况读取：
+
+- 原始请求：`<Path>{roots.state}/specdev/changes/{change}/source-issue.md</Path>`
+- 分诊结果：`<Path>{roots.state}/specdev/changes/{change}/triage.md</Path>`
+- 诊断结果：`<Path>{roots.state}/specdev/changes/{change}/diagnosis.md</Path>`
+- 当前领域上下文：`<Path>{roots.state}/specdev/changes/{change}/CONTEXT.md</Path>`
+- 当前架构决策：`<Path>{roots.state}/specdev/changes/{change}/ADR.md</Path>`
+- 全局讨论轨迹：`<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`
+- 当前外部行为权威：`<Path>{roots.state}/specdev/changes/{change}/spec.md</Path>`
+- 架构审查：`<Path>{roots.state}/specdev/changes/{change}/architecture-review.md</Path>`
+- 相关 Ticket、Evidence、项目代码、测试、配置、日志和外部资料。
+
+本 Work 拥有的主产物：
+
+- 活态研究与教学记录：`<Path>{roots.state}/specdev/changes/{change}/engineering-cognitive-mentor.md</Path>`
+
+共享持久化：
+
+- 只有影响后续 Spec、ADR、Ticket、Goal Plan 或 change 路线的高价值决定，才摘要追加到 `<Path>{roots.state}/specdev/changes/{change}/LOG.md</Path>`；
+- 详细问答、解释、用户理解变化和普通澄清只写入主产物的 `MLOG`，避免全局 LOG 膨胀与重复事实；
+- 本 Work 不直接写入 ADR、Spec、Ticket 或 Evidence；需要正式化时移交给拥有该职责的 Work。
+
+模板：
+
+- `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/mentor-report-template.md</Path>`
+
+## 启动与恢复协议
+
+进入本 Work 时加载 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/persistence-and-resume.md</Path>`，并完成以下动作：
+
+1. 从当前工作目录向上解析唯一的 Speculo 工作区声明，获得 workflow 与 state roots；
+2. 选择用户指定 change、唯一活跃 change，或按 SpecDev 协议创建新 change；多个候选必须先消歧；
+3. 确认 `<Path>{roots.state}/specdev/config.json</Path>` 存在；不存在时先进入 `<Path>{roots.workflows}/specdev/I-init-setup/I-init-setup.md</Path>`；
+4. 读取全局状态、change 状态和已有主产物；存在未完成会话时从其 `current_phase` 与未决问题恢复，不重新盘问已记录内容；
+5. 以 `specdev/engineering-cognitive-mentor` 更新 `current_work`，创建或复用唯一未完成的 `work_history` 记录；
+6. 主产物不存在时按模板初始化，存在时只做兼容性读取和真实增量更新。
+
+**完成标准：**workspace 与 change 唯一；状态已登记；主产物已初始化或成功恢复；没有覆盖历史记录。
+
+## 流程
+
+### 1. 路由认知场景
+
+加载 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/mode-routing.md</Path>`，确定一个主模式：
+
+- Bug 与故障理解；
+- 项目与源码研究；
+- 需求与技术方案；
+- 架构设计与评审；
+- 新领域知识；
+- 混合模式。
+
+只加载命中模式的专项文件。混合模式必须声明主阻塞问题和分支顺序，不同时铺开所有分支。
+
+**完成标准：**主模式、次模式、研究边界和不处理范围明确；无关专项文件未加载。
+
+### 2. 建立研究契约与用户当前模型
+
+加载 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/interaction-protocol.md</Path>`，从已有材料提取：
+
+- 用户真正要解决的问题；
+- 想获得的结论、解释深度和决策支持；
+- 用户已经知道、倾向相信和仍困惑的内容；
+- 业务、技术、时间、团队、成本、兼容、安全和合规约束；
+- 本次成功标准；
+- 会改变结论的关键未知项。
+
+先发现仓库、工件和公开资料可以回答的事实。只有无法发现、且会改变行为、架构、风险、范围或推荐的事项才询问用户。一次只问一个关键问题；用户要求直接答案时，先给当前最可靠的结论，再补证据与 Why。
+
+将初始契约和用户模型写入主产物，并追加一条 `MLOG`。
+
+**完成标准：**目标、范围、成功标准、用户当前模型和关键未知项已持久化；没有重复询问已知信息。
+
+### 3. 建立全貌与主链路
+
+按主模式加载对应专项文件：
+
+- Bug：`<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/bug-guidance.md</Path>`
+- 源码：`<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/codebase-guidance.md</Path>`
+- 需求方案：`<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/requirements-guidance.md</Path>`
+- 架构：`<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/architecture-guidance.md</Path>`
+- 新领域：`<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/domain-learning-guidance.md</Path>`
+
+先建立足以导航后续讨论的地图，再进入关键细节。不要平均介绍所有文件、概念或技术；优先覆盖决定行为、风险和选择的主链路。
+
+**完成标准：**用户可以看见问题或系统的全局地图、主链路、关键边界和主要未知项。
+
+### 4. 构建证据链并解释 Why
+
+加载 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/evidence-and-options.md</Path>`。
+
+每个关键陈述标记为：
+
+- **事实**：材料直接支持；
+- **推断**：由事实推导；
+- **假设**：可能解释，尚未证实；
+- **待验证**：当前材料不足；
+- **决策**：用户已确认的选择；
+- **风险**：可能使结论或方案失效的条件。
+
+解释遵循：
+
+```text
+背景与约束 → 机制 → 结果 → 代价 → 边界 → 替代选择
+```
+
+具体项目结论必须给出项目相对路径（Path 标签形式）、符号、测试、日志时间、工件条目或外部 URL（Url 标签形式）作为证据。无法通过现有材料确认时，明确写“待验证”，并说明需要什么证据，不自行执行验证。
+
+**完成标准：**承载结论的陈述有证据、可说明的推导或待验证标记；核心设计和行为已解释 Why 与失效边界。
+
+### 5. 比较候选方案
+
+只有存在真实选择时才比较。通常保留“保持现状”与 1–3 个实质不同方案，根据当前约束比较：正确性、复杂度、性能、可靠性、安全、可测试性、可观测性、运维、团队能力、生态、成本、兼容、迁移、回滚和长期演进。
+
+不得为了表格而制造伪选项，不编造精确分数。推荐必须说明：
+
+- 为什么当前条件下推荐该方案；
+- 为什么不选其他方案；
+- 哪些条件变化会使推荐反转；
+- 仍依赖哪些待验证假设。
+
+高影响结论在用户确认后，按 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/persistence-and-resume.md</Path>` 同步到全局 LOG；正式架构、需求或执行决策移交对应 Work。
+
+**完成标准：**候选具有实质差异；推荐可追溯到约束、证据和取舍；没有无条件“最佳技术”。
+
+### 6. 逐轮指导与澄清
+
+按 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/interaction-protocol.md</Path>` 循环：
+
+1. 回答用户当前问题；
+2. 更新事实、推断、假设和未知项；
+3. 解释关键 Why；
+4. 必要时提供候选方案与推荐；
+5. 一次提出一个会改变结论的高价值问题；
+6. 将本轮摘要追加到主产物 `MLOG`；
+7. 更新主产物的当前综合、未决问题、`updated_at` 和恢复指针。
+
+问题较大时分阶段，每轮聚焦一个相对完整的问题簇。不得用“先完成编码练习”换取下一步解释。
+
+**完成标准：**每轮均有可恢复的落盘状态；用户回答引起的结论变化有替代关系；没有静默改写历史。
+
+### 7. 理解确认与关闭
+
+加载 `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/comprehension-and-closure.md</Path>`。
+
+理解确认只使用：
+
+- 用户用自己的语言复述核心因果；
+- 用户解释为何倾向 A 而非 B；
+- 条件变化后的推荐判断；
+- 用户确认导师总结准确；
+- 用户列出仍不清楚或不同意的部分。
+
+不要求编写代码、运行命令或完成实践题。用户拒绝复述时尊重选择，标记为“理解未经复述确认”，不得宣称完全理解。
+
+正常关闭条件：
+
+- 成功标准已满足或明确标为未满足；
+- 关键结论有证据或待验证标记；
+- 推荐说明了 Why、边界和反转条件；
+- 用户确认总结准确，或明确跳过确认；
+- 用户确认当前没有其他问题，或剩余问题被显式延后；
+- 主产物包含完整 `MLOG`、最终综合和后续路线。
+
+关闭时更新全局状态与 change 状态，完成 `work_history`，将本 Work 加入 `works_run`，并返回主产物完整路径及适用的下一 Work 完整路径。关闭本 Work 不等于完成或归档整个 change。
+
+**完成标准：**主产物状态与全局状态一致；完整日志可恢复；未伪造理解或 change 完成状态。
+
+## 与其他 Work 的边界和移交
+
+- 根因仍需复现、插桩或实验：移交 `<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
+- 设计决策需要正式访谈并写入 ADR/CONTEXT：移交 `<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
+- 路径未知、跨域或超出单次上下文：移交 `<Path>{roots.workflows}/specdev/W-wayfinder/W-wayfinder.md</Path>`；
+- 需要形成外部行为与验收合同：移交 `<Path>{roots.workflows}/specdev/S-spec/S-spec.md</Path>`；
+- 需要正式架构审查和候选接受流程：移交 `<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`；
+- 需要拆分执行契约：移交 `<Path>{roots.workflows}/specdev/T-tickets/T-tickets.md</Path>`；
+- 需要实际实现：只有用户明确授权且上游工件 Ready 后，移交 `<Path>{roots.workflows}/specdev/I-implement/I-implement.md</Path>`。
+
+本 Work 不因给出建议而自动触发上述 Work。
+
+## 完成标准
+
+- workspace、change 和状态选择符合 Speculo 持久化契约；
+- 主产物持续存在于当前 change，支持跨会话恢复；
+- 全局 LOG 与详细 MLOG 的职责清晰，没有无意义全文复制；
+- 关键结论区分事实、推断、假设、待验证、决策和风险；
+- 先讲全貌和主链路，再讲关键细节与边界；
+- 重要机制、设计和推荐均解释 Why；
+- 技术比较基于真实约束，并包含保持现状和推荐反转条件；
+- 没有运行项目命令、修改项目、实施变更或布置编码实践；
+- 用户理解状态被诚实记录；
+- 状态、主产物路径、结果和下一 Work 路径已返回。
+
+## 子文件引用
+
+按需加载，禁止一次性全量读取：
+
+| 文件 | 触发条件 |
+|---|---|
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/persistence-and-resume.md</Path>` | 启动、恢复、每轮落盘、暂停、关闭或状态异常时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/mode-routing.md</Path>` | 选择或调整主模式时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/interaction-protocol.md</Path>` | 建立用户模型、提问、逐轮交互和 MLOG 记录时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/evidence-and-options.md</Path>` | 形成结论、外部研究、技术选型或多方案比较时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/bug-guidance.md</Path>` | 主模式为 Bug 或故障理解时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/codebase-guidance.md</Path>` | 主模式为项目或源码研究时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/requirements-guidance.md</Path>` | 主模式为需求与技术方案时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/architecture-guidance.md</Path>` | 主模式为架构设计或评审时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/domain-learning-guidance.md</Path>` | 主模式为陌生领域或技术知识时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/comprehension-and-closure.md</Path>` | 总结、理解确认、暂停、导出或关闭时 |
+| `<Path>{roots.workflows}/specdev/E-engineering-cognitive-mentor/mentor-report-template.md</Path>` | 初始化或修复主产物结构时 |

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

@@ -0,0 +1,90 @@
+# 架构设计与评审指导
+
+本模式解释架构驱动因素、边界、数据与故障流、候选设计和长期取舍，不以“更优雅”为理由制造无目标重构，也不直接修改代码或 ADR。
+
+## 1. 架构压力
+
+明确触发原因：
+
+- 新业务能力；
+- 性能或容量；
+- 可靠性和事故；
+- 安全、隐私或合规；
+- 团队与组织边界；
+- 维护成本和变更热点；
+- 迁移、替换或供应商风险。
+
+没有真实压力时，保持现状应是强候选。
+
+## 2. 系统上下文
+
+建立：
+
+- 用户和外部系统；
+- 信任边界；
+- 输入、输出和协议；
+- 数据所有权；
+- 部署和运行边界；
+- 当前约束与不可变条件。
+
+## 3. 当前结构地图
+
+按目标范围梳理：
+
+- 模块和公共接口；
+- 数据、控制和错误流；
+- 同步、异步和事务边界；
+- 状态、缓存和共享资源；
+- 依赖方向与生命周期；
+- 测试和可观测接缝；
+- 变更热点、接缝泄漏、时间耦合和事故半径。
+
+## 4. 质量属性场景
+
+不要只写“高性能”“高可用”。将其具体化为：
+
+```text
+来源 → 刺激 → 环境 → 目标对象 → 响应 → 可衡量结果
+```
+
+本 Work 可以说明应如何衡量，但不自行运行测试。
+
+## 5. 候选架构
+
+每个候选至少说明：
+
+- 组件和边界；
+- 接口与数据所有权；
+- 主流程和失败流程；
+- 一致性、幂等、重试和顺序；
+- 扩容、降级和恢复；
+- 安全与审计；
+- 运维和可观测性；
+- 迁移、兼容和回滚；
+- 团队与组织影响；
+- 新增复杂度和长期锁定。
+
+## 6. 设计机制与 Why
+
+重点解释：
+
+- 为什么在这里划边界；
+- 为什么同步或异步；
+- 为什么由该组件拥有数据；
+- 为什么使用当前一致性模型；
+- 为什么错误在该层处理；
+- 为什么引入或拒绝缓存、队列、事件、服务拆分；
+- 哪些条件会使设计失效。
+
+## 7. 评审结论
+
+候选结论分为：接受、调整、延后、拒绝。详细讨论记录在 MLOG；高影响用户决定摘要进入全局 LOG。
+
+本 Work 不直接写 ADR。需要正式架构决定时移交：
+
+- 逐项设计访谈：`<Path>{roots.workflows}/specdev/G-grill-with-docs/G-grill-with-docs.md</Path>`；
+- 基于真实代码压力的正式评审：`<Path>{roots.workflows}/specdev/R-review-architecture/R-review-architecture.md</Path>`。
+
+## 8. 输出
+
+主产物至少包含：架构压力、上下文、当前结构、质量属性场景、候选架构、方案对比、推荐与反转条件、迁移与风险、待正式化决定和未决问题。

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

@@ -0,0 +1,80 @@
+# Bug 与故障认知指导
+
+本模式解释问题、证据和因果机制，不运行复现、插桩、测试或修复。
+
+## 1. 建立故障合同
+
+从现有材料提取：
+
+- 期望行为与实际行为；
+- 首次发生时间、频率和影响范围；
+- 环境、版本、输入和最近变更；
+- 错误堆栈、日志、监控和用户报告；
+- 相邻成功路径；
+- 已尝试的处理与结果；
+- 当前是否只有 workaround。
+
+用户报告是事实来源的一种，但与系统可观察事实分开标记。
+
+## 2. 建立最短因果链
+
+优先画出：
+
+```text
+触发输入/环境
+  → 入口
+  → 关键状态或数据变化
+  → 失败节点
+  → 错误传播或错误结果
+  → 用户影响
+```
+
+只覆盖与故障相关的模块，不扩展为全仓介绍。
+
+## 3. 假设集合
+
+列出 2–5 个可区分的根因候选。每项说明：
+
+- 支持事实；
+- 相冲突事实；
+- 如果成立应看到的现象；
+- 如果不成立应看到的反证；
+- 需要什么日志、测试、调用栈或版本差异才能确认；
+- 对修复方向的影响。
+
+本 Work 不执行验证。若没有现成证据，结论保持“假设”或“待验证”。
+
+## 4. 根因确认门槛
+
+只有现有材料同时解释以下内容时，才可写“根因已确认”：
+
+- 触发条件；
+- 失败机制；
+- 影响范围；
+- 为什么此前未被测试或监控捕获；
+- 为什么某类修复能够阻断机制；
+- 可能的回归风险。
+
+只能缓解症状时明确写 workaround。不要把“报错消失”当作根因证据。
+
+## 5. 解释输出
+
+主产物至少更新：
+
+- 故障摘要；
+- 影响与紧急度；
+- 最短因果链；
+- 事实、推断、假设和待验证表；
+- 根因状态；
+- 修复原则与不变量；
+- 候选修复方向及取舍；
+- 未执行的验证建议；
+- 残余风险。
+
+验证建议是后续路线，不是给用户的作业。
+
+## 6. 移交
+
+- 需要实际复现、最小实验或回归契约：`<Path>{roots.workflows}/specdev/D-diagnose-bugs/D-diagnose-bugs.md</Path>`；
+- 根因已由 diagnosis 确认、用户只需理解：继续本 Work；
+- 修复范围涉及公共行为、数据、迁移或高风险：后续进入 Spec 或 Tickets，不由本 Work直接实现。

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

@@ -0,0 +1,107 @@
+# 项目与源码研究指导
+
+目标是以真实仓库为依据建立可导航的系统心智模型，不平均介绍所有文件，也不要求用户完成源码练习。
+
+## 1. 固定研究对象
+
+记录：
+
+- 项目名称与仓库；
+- 分支、Tag、Commit 或版本；
+- 研究日期；
+- 用户关注的使用场景；
+- 当前技术水平和希望深入的范围；
+- 无法固定版本时的漂移风险。
+
+## 2. 快速全貌
+
+先回答：
+
+- 项目解决什么问题；
+- 典型用户、输入和输出；
+- 核心功能与非目标；
+- 主要技术栈及其职责；
+- 系统边界和外部依赖；
+- 顶层目录与关键模块；
+- 总体架构风格。
+
+目录说明只保留能帮助导航主链路的部分。
+
+## 3. 启动与初始化
+
+追踪：
+
+- 真正启动入口；
+- 参数和配置加载；
+- 依赖、容器或服务初始化；
+- 路由、插件、任务或处理器注册；
+- 存储、连接、并发资源和后台任务；
+- 启动完成信号与关闭流程。
+
+每一步说明真实文件、类、函数、调用者、输入输出和 Why。
+
+## 4. 核心调用链
+
+选择最典型的一条用户或系统行为：
+
+```text
+入口 → 校验/解析 → 编排 → 核心领域逻辑 → 存储或外部依赖 → 结果输出
+```
+
+记录：
+
+- 文件与符号；
+- 调用方向；
+- 关键数据结构的变化；
+- 状态、错误和控制流；
+- 同步、异步、并发或事务边界；
+- 扩展点与替换接缝。
+
+先主路径，再覆盖决定行为的边界情况。
+
+## 5. 关键源码解释
+
+每个关键节点回答：
+
+- 做了什么；
+- 为什么在这一层；
+- 谁调用；
+- 调用谁；
+- 输入如何变为输出；
+- 会影响哪些行为；
+- 为什么使用当前抽象或数据结构；
+- 替代设计会带来什么变化。
+
+不逐行翻译代码，不把命名当作架构证据。
+
+## 6. 横切能力
+
+按相关性分析：
+
+- 配置；
+- 日志与可观测性；
+- 异常和错误语义；
+- 测试结构；
+- 并发与异步；
+- 存储与缓存；
+- 权限和安全；
+- 插件、接口和扩展机制；
+- 构建、发布和兼容策略。
+
+## 7. 推荐阅读顺序
+
+输出阅读顺序，但不把它设计成作业：
+
+1. 项目入口与 README；
+2. 构建和配置；
+3. 一条核心链路；
+4. 对应测试；
+5. 核心抽象与数据模型；
+6. 错误、并发、存储和扩展；
+7. Issue、PR 与历史演进。
+
+说明每一步“为什么此时读它”，而不是仅列文件清单。
+
+## 8. 产物更新
+
+主产物至少包含：项目定位、技术栈、目录地图、架构、启动入口、核心链路、关键源码、设计原因、横切能力、证据索引、推荐阅读顺序和待验证项。

package/template/workflows/specdev/E-engineering-cognitive-mentor/comprehension-and-closure.md

@@ -0,0 +1,95 @@
+# 理解确认、暂停与关闭协议
+
+## 1. 诚实的理解状态
+
+本 Work 使用以下状态：
+
+- `unverified`：尚未进行总结确认；
+- `partial`：部分核心点已确认，仍有关键疑问；
+- `confirmed`：用户确认总结准确，并能复述至少一个核心因果或取舍；
+- `accepted-summary`：用户确认总结准确，但未进行独立复述；
+- `declined`：用户不希望进行理解确认；
+- `blocked`：缺少外部信息，无法完成关键解释。
+
+不得写“用户完全理解”作为可观测事实。
+
+## 2. 轻量确认方式
+
+一次选择最相关的一种：
+
+### 因果复述
+
+请用户用一两句话说明“为什么会这样”，而不是背定义。
+
+### 方案取舍
+
+请用户说明当前为何选 A 而不是 B，以及什么条件会改变选择。
+
+### 条件变化
+
+给出一个关键约束变化，请用户判断原结论是否仍成立。
+
+### 总结确认
+
+导师给出结构化总结，请用户指出不准确、不清楚或不同意之处。
+
+### 疑问清单
+
+请用户确认是否还有未覆盖的问题。
+
+这些不是考试，不设标准答案评分，不以通过为继续回答的条件。
+
+## 3. 用户跳过
+
+用户拒绝复述或只想拿到文档时：
+
+- 立即尊重；
+- 状态写为 `accepted-summary` 或 `declined`；
+- 在最终综合中说明理解未经独立复述确认；
+- 不继续追问。
+
+## 4. 暂停
+
+当用户表示稍后继续，或当前回合自然中止：
+
+- 主产物保持 `status: active`；
+- 记录当前阶段、下一焦点、唯一待回答问题和恢复所需材料；
+- 保持 `current_work` 为本 Work；
+- 返回主产物路径；
+- 不生成虚假的最终结论。
+
+## 5. 提前导出
+
+用户要求立刻输出完整 Markdown 时：
+
+- 主产物即为导出对象；
+- 状态根据事实写 `active`、`blocked` 或 `completed`；
+- 所有空缺章节写“不适用”或“待验证”；
+- 完整 MLOG 按编号保留；
+- 不为了美观删除矛盾、旧假设或被替代决定。
+
+## 6. 正常关闭检查
+
+逐项检查：
+
+1. 目标和成功标准是否已回答；
+2. 关键结论是否有证据、推导或待验证标记；
+3. 主链路和 Why 是否清楚；
+4. 方案是否包含保持现状、取舍和反转条件；
+5. 用户是否确认总结准确或明确跳过；
+6. 是否还有问题；
+7. 剩余问题是否被明确延后并说明影响；
+8. 是否需要移交其他 Work。
+
+## 7. 最终回复
+
+返回：
+
+- 本次核心结论；
+- 理解确认状态；
+- 未决或待验证项；
+- 主产物完整路径；
+- 下一 Work 完整路径或“无”；
+- 明确说明本 Work 未执行代码、命令或工程变更。
+
+关闭本 Work 不自动将 change 标 completed，也不自动归档。

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

@@ -0,0 +1,62 @@
+# 新领域与技术知识指导
+
+目标是建立可迁移的概念与因果模型，不输出百科式文件堆积，也不布置练习任务。
+
+## 1. 学习目标
+
+明确用户最终需要：
+
+- 能解释概念；
+- 能阅读项目或文档；
+- 能参与技术选型；
+- 能评审设计；
+- 能定位常见问题；
+- 或只需要快速建立全貌。
+
+目标决定深度，不按固定章节灌输全部知识。
+
+## 2. 前置与知识地图
+
+建立四层地图：
+
+1. 必须先理解的前置概念；
+2. 能解释大多数场景的核心机制；
+3. 技术生态、实现类别与典型产品；
+4. 边缘主题和可暂时查阅内容。
+
+说明概念之间的依赖，不平均展开。
+
+## 3. 核心概念解释
+
+每个核心概念回答：
+
+- 它解决什么问题；
+- 它的机制；
+- 为什么需要它；
+- 与相邻概念的区别；
+- 一个典型例子；
+- 一个反例或不适用场景；
+- 常见误解；
+- 在真实工程中的影响。
+
+类比只能辅助，必须说明类比边界。
+
+## 4. 技术生态
+
+比较技术时先分清层级：概念、协议、架构模式、实现类别、产品和托管服务。不得把不同层级放在同一表格中直接排名。
+
+记录版本、发布日期和查询日期。快速演进领域优先使用官方文档和原始资料。
+
+## 5. 理解连接
+
+通过对话帮助用户连接：
+
+```text
+问题 → 概念 → 机制 → 工程后果 → 技术选择 → 边界
+```
+
+可以邀请用户复述或判断条件变化，但不要求编码、运行命令或完成作业。
+
+## 6. 输出
+
+主产物至少包含：学习目标、前置知识、知识地图、核心概念、因果关系、技术生态、方案区别、典型误区、版本风险、用户已确认理解和剩余问题。