npm - @namewta/speculo - Versions diffs - 0.1.3 → 0.1.5 - Mend

@namewta/speculo 0.1.3 → 0.1.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md CHANGED Viewed

@@ -60,12 +60,13 @@ speculo update my-project
 - `workflows/dev/03-tdd/03-tdd.md`：TDD 实现
 - `workflows/dev/I-to-issues/I-to-issues.md`：`dev/I` 垂直切片分解
 - `workflows/dev/H-diagnose/H-diagnose.md`：`dev/H` hotfix / diagnose
-- `workflows/dev/R-review/R-review.md`：`dev/R` 双维度 diff 审查
+- `workflows/dev/R-review/R-review.md`：`dev/R` Spec / Engineering / Standards 三维度 diff 审查
 - `workflows/dev/D-docs-sync/D-docs-sync.md`：`dev/D` git diff 驱动文档同步
 - `workflows/doc/00-INDEX.md`：文档写作 workflow 导航
 - `commands/status.md`：聚合当前状态
 - `commands/archive.md`：归档 completed change
 - `commands/{caveman,grill-me,handoff,write-a-skill,scaffold-exercises}.md`：生产力命令
+- `commands/retro.md`：复盘 Speculo 使用痛点并经确认提改进 issue
 ## 开发
@@ -77,6 +78,13 @@ pnpm test
 运行环境锁定为 Node `22.22.3`、pnpm `11.1.3`。
+## 致谢 / Acknowledgements
+Speculo 的设计受益于以下项目的理念与实践：
+- **[Matt Pocock / skills](https://github.com/mattpocock/skills)** — 技能封装与渐进披露模式的重要参考
+- **[NAMEWTA / specforge](https://github.com/NAMEWTA/specforge)** — 同属 SDD 工具链的兄弟项目，规格生成与验证的互补实践
 ## 文档导航
 - 使用者必读：[adopting.md](docs/adopting.md) · [quick-reference.md](docs/quick-reference.md)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@namewta/speculo",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Speculo — specification-driven development framework assets, with a CLI to install and update them across AI coding tools.",
   "type": "module",
   "bin": {

package/speculo/commands/retro.md ADDED Viewed

@@ -0,0 +1,68 @@
+---
+id: retro
+type: command
+name: Speculo Retro
+description: 复盘 Speculo commands/workflows 使用痛点，深度分析后经确认用 gh 提交改进 issue
+keywords: [retro, 复盘, 痛点, feedback, issue, 优化, 反馈]
+---
+# Retro 命令
+⚠️ **本命令在最后一步会通过 `gh` 向外部仓库创建 issue（外部写操作）。AI 必须先列出将要创建的 issue 清单与目标仓库并征求用户确认，确认前只输出计划，不调用 `gh`。**
+## 归档路径模式
+产物目录：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`
+报告文件：`../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`
+- `<YYYY-MM-DD>` 使用当前日期。
+- `<topic>` 从复盘范围或用户主题提取，使用小写 kebab-case；无法判断时使用 `speculo`。
+- 安装后的实际项目位置是 `speculo/.speculo/commands/<YYYY-MM-DD>-retro-<topic>/report.md`。
+- 禁止把命令报告写入 `temp/`、系统临时目录或工作区内其他非规范位置。
+## 调用的 skills
+- `../skills/speculo-retro/SKILL.md` — 复盘 Speculo 使用痛点、深度分析并产出去重/分级/根因化的 issue-ready 提案时读取。
+- `../skills/github-npm-ops/SKILL.md` — 需要用 `gh` 去重（`gh issue list --search`）与创建 issue（`gh issue create`）时读取，其 `references/issue-pr-triage.md` 提供检索、标签体系与命令模板。
+## 执行步骤
+1. 读取 `../skills/speculo-retro/SKILL.md`，按其规范采集信号（对话上下文、`../.speculo/commands/`、`../.speculo/<cat>/<change>/.status.json`、`../.speculo/.config/LESSONS.md`）并深度分析。
+2. 用该 skill 产出规范化复盘结论：去重、分级、根因化的 issue-ready 提案清单，附丢弃/合并说明与每条处置建议。
+3. 创建规范命令产物目录 `../.speculo/commands/<YYYY-MM-DD>-retro-<topic>/`，把复盘结论写入 `report.md`。
+4. **解析目标仓库**：默认框架反馈上游 `NAMEWTA/Speculo`；用户在请求中显式指定其他 `owner/repo` 时覆盖默认。无论如何，在调用 `gh` 前回显解析到的 `owner/repo`，让用户确认或改正。
+5. **去重**：读取 `../skills/github-npm-ops/SKILL.md` 的 `references/issue-pr-triage.md`，对每条 `disposition: file-issue` 的提案用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索；命中语义重复的默认跳过并记录 `dup_of`，仅当用户明确要求才补提。
+6. **外部写操作边界**：向用户展示将要创建的 issue 清单（标题、类型/优先级标签、正文摘要、目标 `owner/repo`）与去重结果，等待用户明确确认。没有确认时只输出计划，不调用 `gh`。
+7. 用户确认后，按优先级倒序逐条执行 `gh issue create --repo <owner/repo> --title "<title>" --body "<body>" --label "<type>,<priority>[,<area>]"`（多行正文可用 `--body-file` 指向不保留的临时文件）。任一条失败时停止后续创建，报告已建/未建清单，不重复创建同一条。
+8. 把每条提案的最终 issue 编号/URL 回写进 `report.md` 的「提交结果」小节；返回 `report.md` 路径、3-5 条复盘摘要和已创建 issue 链接清单。
+## 产物模板（report.md）
+> **服务命令：** `retro.md`
+> **产物文件名：** `report.md`
+```markdown
+# Speculo Retro Report
+## 复盘范围
+[TODO: 本次复盘覆盖的 command / workflow 与时间/会话范围。]
+## 信号来源
+[TODO: 列出采集到的证据出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、LESSONS。]
+## 改进提案
+[TODO: 按优先级倒序列出每条提案：标题 / 类型 / 优先级 / 根因 / 建议改动 / 验收标准 / 受影响资产 / 去重结论。]
+## 丢弃与降级项
+[TODO: 列出被合并、丢弃或降级为「仅记教训」的项及原因。]
+## 目标仓库
+[TODO: 解析到的 owner/repo 与用户确认结果。]
+## 用户确认记录
+[TODO: 记录用户对 issue 清单与目标仓库的确认原文摘要。]
+## 提交结果
+[TODO: 列出每条提案对应的 issue 编号/URL，或未提交原因（重复/失败/用户撤回）。]
+```

package/speculo/skills/speculo-retro/SKILL.md ADDED Viewed

@@ -0,0 +1,52 @@
+---
+id: speculo-retro
+type: skill
+name: Speculo Retro
+description: 复盘 Speculo commands/workflows 使用过程中的痛点、问题与值得优化的地方，深度分析后产出去重、分级、根因化、可直接转成 GitHub issue 的规范化改进提案；当用户要求总结 Speculo 使用体验、收集框架反馈或把使用痛点整理成 issue 时使用。
+---
+# Speculo Retro
+## 何时使用
+当用户想复盘「用 Speculo 的 commands 或 workflows 时遇到的痛点、问题、值得优化的地方」，并希望把这些摩擦整理成规范化、可行动的框架反馈或 issue 时使用。
+典型触发：
+- “总结一下这次用 Speculo 踩的坑 / 卡点”
+- “把使用痛点整理成可以提的 issue”
+- “复盘 dev workflow 哪里别扭、哪里值得优化”
+- “收集 Speculo 框架反馈”
+本 skill 只负责**分析与规范化产出内容**：它去重、分级、根因化并起草 issue-ready 提案，把结果返回给调用方。它**不自行写文件、不调用 `gh`、不发布 issue**；落盘与提交由调用方 command / workflow 负责。
+## 输入
+- 当前对话上下文：本次会话用了哪些 command / workflow、卡在哪、绕了什么弯、重复了哪些动作
+- `.speculo/commands/<run>/` 下的历史命令产物（report、snapshot、handoff）
+- `.speculo/<cat>/<change>/` 下的 change 产物与 `.status.json`（`phase_history` 里的 `revisited`、`blocked`、长时间停滞都是摩擦信号）
+- `.speculo/.config/LESSONS.md`（已沉淀的教训，用于去重与佐证）
+- 可选：调用方提供的已存在 issue 列表或目标仓库上下文，用于跨提案去重
+- 本 skill 自带分析与 issue 起草规范，已内化到 `references/`，分析时**不外读仓库 `docs/`**
+## 输出
+- 规范化复盘结论：每条 = 一个去重、分级、根因化的改进提案，字段对齐 GitHub issue（标题、类型/标签、证据、问题、建议改动、验收、受影响 asset）
+- 提案清单，按优先级倒序排列
+- 被合并或丢弃的低信号项说明（哪些重复、哪些更适合记入 `LESSONS.md` 而非提 issue）
+- 每条标注「建议提 issue」或「仅记教训」的处置建议
+- 全部以**返回内容**形式交给调用方写入其声明的 `.speculo/...` 路径；本 skill 不挑选持久化位置
+## 执行步骤
+1. **收集信号** —— 按 `references/friction-taxonomy.md` 的来源清单，扫描对话上下文、`.speculo/` 产物与 `LESSONS.md`，列出原始摩擦点。
+2. **归类与去重** —— 按 taxonomy 把每个摩擦点归到类型（bug / friction / missing-capability / doc-gap / ergonomics），合并语义重复项。
+3. **深度分析** —— 对每条做根因判断（是 asset 设计、持久化契约、文档还是工具问题），评估影响面与发生频率，按 `references/friction-taxonomy.md` 的优先级评分。
+4. **过滤噪声** —— 只保留高信号、可行动项；低信号或一次性项标注为丢弃，或归入「仅记教训」。
+5. **起草提案** —— 按 `references/issue-drafting-sop.md` 把每条规范化成 issue-ready 提案，并对照调用方提供的已存在 issue 做跨提案去重。
+6. **返回结论** —— 把结构化提案清单、丢弃项与处置建议返回调用方；不自行写文件、不调用 `gh`。
+## 渐进披露
+- `references/friction-taxonomy.md`：确定信号来源、给摩擦点归类、按影响 × 频率评优先级、过滤噪声时读取。
+- `references/issue-drafting-sop.md`：把改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成给调用方 / `gh` 的交接字段时读取。

package/speculo/skills/speculo-retro/references/friction-taxonomy.md ADDED Viewed

@@ -0,0 +1,55 @@
+# Friction Taxonomy SOP
+复盘 Speculo 使用摩擦时的信号来源、分类法、优先级评分与噪声过滤规范。
+## 信号来源清单
+按以下顺序采集原始摩擦点，每条记录**证据出处**（文件路径或对话节点），后续起草 issue 时要引用：
+1. **当前对话上下文** —— 本次会话激活过的 command / workflow；用户在哪一步卡住、追问、返工；为绕开限制做了哪些手动动作；哪些指令被误解。
+2. **命令产物** —— `.speculo/commands/<run>/` 下的 `report.md`、`snapshot.md`、`handoff.md`：里面记录的「验证失败原因」「未完成」「阻塞点」是一手摩擦。
+3. **change 状态机** —— `.speculo/<cat>/<change>/.status.json` 的 `phase_history`：
+   - `revisited` —— phase 被迫回退，通常意味着流程设计或前置产物有缺口
+   - `blocked` —— 卡点，记录阻塞原因
+   - `skipped` —— phase 被跳过，可能是冗余或不适用
+   - `updated_at` 长期停滞 —— 流程让人不想推进
+4. **change 产物正文** —— `prd.md`、`tdd-*.md`、`slices.md`、`diagnosis.md` 中显式写下的「待澄清」「风险」「TODO」。
+5. **沉淀教训** —— `.speculo/.config/LESSONS.md`：已记录但尚未转成改进项的教训，用于去重与佐证频率。
+6. **契约落差** —— 实际产物路径、frontmatter、命名是否偏离 `persistence-contract`：路径散落、缺字段、命名不合 `YYYY-MM-DD-<kebab>` 都是 bug 信号。
+## 摩擦类型分类
+每个摩擦点归且仅归一个**主类型**：
+| 类型 | 含义 | 典型表现 |
+|------|------|---------|
+| `bug` | 资产行为不符合契约或文档 | 产物写错位置、`.status.json` 缺字段、命令覆盖了用户改动 |
+| `friction` | 能用但别扭、步骤冗余、易错 | 反复手动改路径、phase 频繁 `revisited`、确认环节缺失 |
+| `missing-capability` | 缺一个本该有的 command/workflow/skill | 用户手动拼凑某个反复出现的流程 |
+| `doc-gap` | 文档缺失、过时或与实现不符 | 指引说一套、资产做另一套；找不到用法 |
+| `ergonomics` | 命名、触发词、措辞、可发现性 | description 区分度差、关键词命中不到、术语不一致 |
+## 优先级评分
+优先级 = **影响面 × 发生频率**，落到四档（复用 `github-npm-ops` 标签体系）：
+- 影响面：`broad`（影响所有使用者 / 破坏契约）｜`partial`（影响部分流程）｜`cosmetic`（轻微体验）
+- 发生频率：`recurring`（多次出现 / 多来源佐证）｜`occasional`｜`one-off`
+| 优先级 | 判定 |
+|--------|------|
+| `priority:critical` | 破坏契约、数据/产物丢失、覆盖用户改动 —— 无论频率 |
+| `priority:high` | `broad` 影响且 `recurring`，或显著阻塞主流程 |
+| `priority:medium` | `partial` 影响，或 `broad` 但仅 `occasional` |
+| `priority:low` | `cosmetic`，或 `one-off` 且有 workaround |
+## 噪声过滤规则
+不是每个摩擦点都该变成 issue。按以下规则收敛：
+- **合并** —— 语义重复的多条合成一条，频率累加（提升优先级佐证）。
+- **丢弃** —— 纯属本次会话一次性、不可复现、或已被其他提案覆盖的，标注「丢弃」并写明原因。
+- **降级为教训** —— 属于「用法/约定」而非「资产缺陷」的，建议记入 `LESSONS.md` 而非提 issue。
+- **可行动性闸门** —— 无法描述出「改哪个 asset、怎么改、怎么验收」的，先标 `needs-design`，不要凭空提模糊 issue。
+只把通过闸门、`priority:medium` 及以上、或 `recurring` 的高信号项推进到 issue 起草。

package/speculo/skills/speculo-retro/references/issue-drafting-sop.md ADDED Viewed

@@ -0,0 +1,77 @@
+# Issue Drafting SOP
+把通过过滤的改进提案规范化成 issue-ready 结构、对照已存在 issue 去重、生成交给调用方 / `gh` 的交接字段。
+## 提案字段（issue-ready）
+每条提案产出以下结构化字段，调用方据此写报告并据此调 `gh`：
+```jsonc
+{
+  "title":        "string, 见标题规范",
+  "type":         "bug | enhancement | documentation | feature-request",
+  "priority":     "priority:critical | priority:high | priority:medium | priority:low",
+  "area":         "string|null, 例 area:commands / area:workflows / area:skills / area:cli / area:contract",
+  "body":         "string, 见正文结构",
+  "affected":     ["相对路径，例 speculo/commands/archive.md"],
+  "evidence":     ["证据出处，例 .speculo/dev/<change>/.status.json#phase_history"],
+  "disposition":  "file-issue | record-lesson | drop",
+  "dup_of":       "number|null, 疑似重复的已存在 issue 编号"
+}
+```
+## 标题规范
+- 用祈使句描述「要改成什么」，不是「哪里坏了」：`命名` 区分度差 ❌ → `enhancement: 提升 command description 在系统提示里的区分度` ✅
+- 前缀对齐类型：`bug:` / `enhancement:` / `docs:` / `feature:`
+- 单行、可独立读懂、不超过约 70 字，含受影响的 asset 名。
+## 类型 → 标签映射
+复用 `../github-npm-ops/references/issue-pr-triage.md` 的标签体系，每条至少一个**类型**标签，外加**优先级**，可选**领域**：
+| 提案 type | issue 类型标签 |
+|-----------|---------------|
+| `bug` | `bug` |
+| `friction` | `enhancement` |
+| `missing-capability` | `feature-request` |
+| `doc-gap` | `documentation` |
+| `ergonomics` | `enhancement` |
+不确定改动方向的额外加 `needs-design`。
+## 正文结构
+每条 issue body 用固定小节，占位符填实，禁止空话：
+```markdown
+## 问题
+[一句话说清痛点 / 不符合预期的行为。]
+## 证据
+[引用具体出处：对话节点、`.speculo/...` 产物路径、`.status.json` 字段、文档段落。可附最小复现。]
+## 根因
+[判断是 asset 设计 / 持久化契约 / 文档 / 工具问题，指明根因而非表象。]
+## 建议改动
+[改哪个 asset、怎么改。给相对路径与具体方向，不要泛泛而谈。]
+## 验收标准
+[可验证的完成判据，例如断言、命名、契约符合点。]
+## 受影响资产
+[列出相关相对路径。]
+```
+## 去重
+起草后、交给调用方提交前，对每条做去重判定：
+1. 提取标题与根因的关键词。
+2. 由调用方用 `gh issue list --repo <owner/repo> --search "<关键词>" --state all --limit 20` 检索（机制见 `../github-npm-ops/references/issue-pr-triage.md`）。
+3. 命中语义重复：把 `disposition` 设为 `drop` 或在 `dup_of` 记录已存在编号，默认不重复提；仅当用户明确要求才补提。
+## 交接契约
+本 skill 只返回上面的结构化提案清单 + 丢弃/合并说明，**不写文件、不调用 `gh`、不创建 issue**。落盘到 `.speculo/commands/<run>/report.md` 与实际 `gh issue create` 由调用方 command 在用户确认后执行。

package/speculo/workflows/dev/03-tdd/03-tdd.md CHANGED Viewed

@@ -58,15 +58,15 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - 完成准则：
   - 已运行相关测试或明确记录无法运行原因
   - 无调试残留和推测性功能
-  - 已把 roadmap 中该阶段 `<phase>` 状态由 `未开始` 置为 `已实现`（无 roadmap 则跳过，见「roadmap 阶段状态（XML 契约）」）
+  - 已把 slices 中该阶段 `<phase>` 状态由 `未开始` 置为 `已实现`（无 slices 则跳过，见「phase 阶段状态（XML 契约）」）
   - `verification.md` 无残留 `[TODO:]`
 ## TDD 产物目录与阶段标识
-- 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / roadmap 等产物分离，便于多阶段并行与回溯。
+- 本工作流所有产物集中在 `.speculo/dev/<change>/tdd/<phase-id>/`，与 change 根目录的 PRD / slices 等产物分离，便于多阶段并行与回溯。
 - `<phase-id>` 标识：
-  - change 来自**多阶段 roadmap** 时，用 roadmap 阶段标识（与 roadmap `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
-  - change 为**单阶段**（无 roadmap 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。
+  - change 来自**多阶段 slices** 时，用 slices 阶段标识（与 slices `<phase id="...">` 的 `id` 严格一致），如 `phase0-node-base`、`phase1-templates`。
+  - change 为**单阶段**（无 slices 分期）时，用一个描述性切片 slug，如 `phase0-<slug>`。
 - 每个阶段独立一套 `tdd-plan.md` / `implementation-log.md` / `verification.md`，互不覆盖；模板顶部「阶段标识」段记录该 `<phase-id>`。
 - 目录形如：
@@ -82,9 +82,9 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
     └── verification.md
 ```
-## roadmap 阶段状态（XML 契约）
+## phase 阶段状态（XML 契约）
-多阶段 roadmap（`.speculo/dev/<change>/roadmap.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
+多阶段 change（`.speculo/dev/<change>/slices.md`）中，每个阶段标题下紧跟一个状态标记，作为该阶段在三段生命周期中的单一事实源：
 ```xml
 <phase id="phase0-node-base" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
@@ -92,11 +92,11 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - `id`：阶段稳定标识，与 TDD 产物目录 `tdd/<phase-id>/` 同名。
 - `status` 枚举与责任方：
-  - `未开始` —— 创建 roadmap 文档时由作者初始化（所有阶段默认 `未开始`）。
+  - `未开始` —— 创建 slices 文档时由作者初始化（所有阶段默认 `未开始`）。
   - `已实现` —— 本工作流（`dev/03`）该阶段 Finish 验证通过后置入。
   - `已验证` —— `dev/04`（`../04-finalize/04-finalize.md`）完成前验证通过后置入。
 - 本工作流只负责 `未开始 → 已实现` 这一跳；`dev/04` 负责 `已实现 → 已验证`。状态只前进不回退，除非该阶段被显式重做。
-- change 无 roadmap（单阶段直接任务）时本契约不适用，跳过状态翻转。
+- change 无 slices（单阶段直接任务）时本契约不适用，跳过状态翻转。
 ## 依赖
@@ -109,7 +109,7 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - `dev_entry` (string) — 固定为 `dev/03`
 - `embedded_guides` (array) — 包含 `tdd`
-- `tdd_phase_id` (string) — 当前 TDD 阶段标识，与产物目录 `tdd/<phase-id>/` 及 roadmap `<phase>` 的 `id` 一致
+- `tdd_phase_id` (string) — 当前 TDD 阶段标识，与产物目录 `tdd/<phase-id>/` 及 slices `<phase>` 的 `id` 一致
 - `slice_source` (prd | issues | diagnosis | user-request) — 切片来源
 - `red_green_refactor_cycles` (array) — 每轮 TDD 循环摘要
 - `verification_commands` (array) — 已运行或应运行的验证命令
@@ -121,5 +121,5 @@ keywords: [tdd, implement, red-green-refactor, 实现, 测试]
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 每完成一个切片，追加 `red_green_refactor_cycles`（多阶段时写入 `tdd_runs[<phase-id>]`）。
-- Finish 验证通过后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 roadmap 则跳过）。
+- Finish 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（无 slices 则跳过）。
 - 全部用户要求的实现边界完成并验证后，可把 `change_status` 置为 `completed`，或移交 review/handoff command。

package/speculo/workflows/dev/03-tdd/tdd-finish.md CHANGED Viewed

@@ -15,7 +15,7 @@
 1. 运行与变更相关的测试、类型检查、lint 或构建命令。
 2. 记录无法运行的命令和阻塞原因。
 3. 搜索临时调试标记、一次性脚本和推测性实现。
-4. 验证通过后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「roadmap 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 roadmap 则跳过）。
+4. 验证通过后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `未开始` 置为 `已实现`（契约见 `03-tdd.md`「phase 阶段状态（XML 契约）」；本工作流只做这一跳，`已验证` 由 `dev/04` 置入；无 slices 则跳过）。
 5. 如有可沉淀经验，记录在 `verification.md` 的后续建议中；在用户允许或项目规则允许时追加到 `.speculo/.config/LESSONS.md`。
 ## 边界
@@ -25,6 +25,6 @@
 ## 完成准则
-- 多阶段 roadmap：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 roadmap 则不适用）
+- 多阶段 slices：该阶段 `<phase>` 的 `status` 已由 `未开始` 置为 `已实现`（无 slices 则不适用）
 - `verification.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `verified` 或 `blocked`

package/speculo/workflows/dev/03-tdd/tdd-plan.md CHANGED Viewed

@@ -26,6 +26,6 @@
 ## 完成准则
-- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 roadmap 须与 `<phase>` 的 `id` 一致）
+- 产物顶部「阶段标识」段已填写 `<phase-id>`（多阶段 slices 须与 `<phase>` 的 `id` 一致）
 - `tdd-plan.md` 无残留 `[TODO:]`
 - `.status.json` 的 `implementation_status` 为 `planned`

package/speculo/workflows/dev/04-finalize/04-finalize.md CHANGED Viewed

@@ -126,7 +126,7 @@ keywords: [finalize, verify, complete, archive, 归档, 收尾, 完成验证]
 - 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
 - 完成验证后写入 `verification_commands`、`requirements_checklist`、`verification_status`。
-- 多阶段 roadmap：完成前验证为 `verified` 后，把 roadmap 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `已实现` 置为 `已验证`（承接 `../03-tdd/03-tdd.md`「roadmap 阶段状态（XML 契约）」的最后一跳；无 roadmap 则跳过）。
+- 多阶段 slices：完成前验证为 `verified` 后，把 slices 中该阶段 `<phase id="<phase-id>">` 的 `status` 由 `已实现` 置为 `已验证`（承接 `../03-tdd/03-tdd.md`「phase 阶段状态（XML 契约）」的最后一跳；无 slices 则跳过）。
 - 验证为 `blocked` 时停在本工作流，回到 `../03-tdd/03-tdd.md` 或 `../H-diagnose/H-diagnose.md` 修复，不归档。
 - 验证为 `verified` 且用户确认后：
   - **worktree 模式**：先执行 Phase 2，自动把 change 分支合并回 `base_branch` 并清理工作树与隔离分支（`worktree_status: merged` → `removed`，冲突即停），再在 base 分支上归档；非 worktree 模式跳过 Phase 2。

package/speculo/workflows/dev/04-finalize/completion-gate.md CHANGED Viewed

@@ -37,5 +37,5 @@
 - 需求清单逐项核对完成，含来源引用
 - 调试残留已清理或明确说明
 - `completion-verification.md` 无残留 `[TODO:]`
-- 多阶段 roadmap：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 roadmap 则不适用）
+- 多阶段 slices：本阶段对应的 `<phase>` 状态已由 `已实现` 置为 `已验证`（无 slices 则不适用）
 - `.status.json` 写入 `verification_commands`、`requirements_checklist`、`verification_status`

package/speculo/workflows/dev/I-to-issues/issues-slices.md CHANGED Viewed

@@ -1,31 +1,108 @@
 # Slice Issues Phase
+> 本阶段将 PRD、计划或诊断结论拆为**可独立验证的垂直切片**（tracing bullet），产出兼具路线图信息密度的 `slices.md`。
+> `slices.md` 融合了原 roadmap.md 的阶段规划能力——按 scope / architecture / phases / cross-cutting / dependency 五段结构组织，
+> 同时保留 HITL/AFK 标记、用户确认与 issue 发布流程。
 ## 输入
 - `prd.md`、`decision-log.md`、`diagnosis.md`、现有 issue 或用户计划
 - 可选 issue tracker 配置和标签词汇表
 - `I-to-issues.md` 中的内置切片指引
+- 同级 change 目录下已有的 `context-map.md`、`decision-log.md`（若存在，用于继承领域术语与 ADR 引用）
 ## 产物
 - `.speculo/dev/<change>/slices.md`，由 `../_templates/issues-slices-template.md` 填写
+## `slices.md` 格式规范（五段结构）
+`issues-slices-template.md` 提供模板骨架；AI 在填写时**必须**按以下五段结构展开，使 `slices.md` 融合 roadmap.md 的信息密度：
+### 0. 一句话战略（strategic anchor）
+单句概括本 change 的「做什么 + 为什么 + 怎么做到（以现有系统为基底 / 新建 / 复用）」。从 PRD 或用户意图提炼，为后续所有切片提供决策锚点。
+### 1. 范围边界（IN / REUSE / OUT）
+三列表格，逐条列出：
+- **IN** —— 本次必造的新能力（每项可对应后续一个或多个切片）
+- **REUSE** —— 复用现有系统的能力（不改动，只收编进新地基）
+- **OUT** —— 本期不做、留给后续迭代的内容
+表格来源优先从 PRD 或用户指令提取；若来源未明确，用 `[待确认]` 标记并提请用户补充。
+### 2. 架构上下文（可选，有则填）
+若 change 涉及多模块或改动既有架构，本节记录：
+- 涉及的 `core/` / `src/` / `src-tauri/` 模块及其职责分工
+- 新增模块的定位（一句话职责 + 落点目录）
+- 不可逾越约束（来自 `AGENTS.md` 或 PRD 的硬性规则）
+本节不是必需的；单文件修复或热点 patch 可省略。
+### 3. 切片（phases）
+每个切片是**一个从数据到 UI 的端到端闭环**（窄而完整）。切片按依赖顺序排列；每个切片包含：
+```markdown
+### 切片 N · 切片名称
+<phase id="<phase-id>" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+- **类型：** `AFK` | `HITL`
+- **阻塞于：** 切片 M（或「无」）
+- **覆盖：** PRD 章节 / US 编号 / 用户故事简述
+- **交付物：** 该切片产出的具体文件/模块/功能清单
+- **复用：** 复用哪些现有能力（模块/文件/命令）
+- **验收切片：** 一个可独立执行的验证命令或手动检查步骤，证明本切片完成
+- **对齐：** PRD FR-xxx 或 issue 引用
+- **ADR 引用：** （可选）关联的工程层 ADR 编号
+```
+- `<phase id="...">` 是稳定的阶段标识（如 `phase0-node-base`、`phase1-templates`），供 `dev/03` TDD 工作流引用。单阶段 change 用 `phase0-<slug>`。
+- `status` 枚举：`未开始`（切片创建时） → `已实现`（TDD finish 置入） → `已验证`（finalize 置入）。状态只前进不回退。
+### 4. 横切关注点（贯穿所有切片）
+列出跨切片一致的规则与约束，如：
+- 磁盘契约先改 zod + fixtures 再改解析
+- 删缓存可重建铁律
+- 范围隔离规则（不 import 旧 AI 子系统等）
+- 命名消歧规则
+### 5. 依赖顺序速查
+ASCII 依赖链，展示切片先后顺序：
+```
+P0  切片0  名称    ← 不可回退,最先
+P1  切片1  名称
+P2  切片2  名称    依赖 P0+P1
+...
+```
+> **判据：** 每个切片的「验收切片」全部通过即该切片完成；所有切片完成 = change 可进入 `dev/04` 收尾。
 ## 填写引导
-1. 遵循 `I-to-issues.md` 的内置切片指引。
-2. 先本地起草切片，按垂直切片原则覆盖端到端行为。
-3. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记和是否需要发布。
-4. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
-5. 每个切片展示标题、类型、被哪些切片阻塞、覆盖的用户故事或来源。
-6. 迭代直到用户批准分解；未批准前不发布外部 issue。
+1. 遵循 `I-to-issues.md` 的内置切片指引和本文件的五段格式。
+2. **采集来源**：从 PRD / decision-log / diagnosis / 用户指令中提取 IN/REUSE/OUT 三列、架构上下文和 ADR 引用；不确定的标记 `[待确认]`。
+3. **切分垂直切片**：优先窄而完整、优先 AFK；每个切片必须有用户可独立验证的「验收切片」。
+4. **标注 phase id**：为每个切片生成稳定的 `<phase id="...">` 标识（kebab-case），供 TDD 阶段直接引用。
+5. 用编号列表向用户确认粒度、依赖、HITL/AFK 标记、phase id 和是否需要发布外部 issue。
+6. 按依赖顺序记录切片；发布外部 issue 时也按依赖顺序发布。
+7. 迭代直到用户批准分解；未批准前不发布外部 issue。
 ## 边界
 - 不关闭或修改父级 issue。
 - 不默认发布到外部 tracker。
 - 不写实现代码。
+- 不编造来源；PRD/ADR/issue 引用必须真实存在。
 ## 完成准则
 - `slices.md` 无残留 `[TODO:]`
+- 每个切片都有 `<phase id="...">` 标识、类型、依赖、覆盖来源、验收切片
+- IN/REUSE/OUT 表格完整（无法确定时标 `[待确认]` 并已获用户补充）
 - `.status.json` 已记录 `slice_count`、`hitl_slice_count` 和 `issue_tracker_mode`

package/speculo/workflows/dev/_templates/issues-slices-template.md CHANGED Viewed

@@ -3,17 +3,64 @@
 # Vertical Slices
-## 来源
-[TODO: 记录切片来源，如 PRD、计划、诊断结论、issue 或用户请求。]
+> 本文件融合了 roadmap 的 scope/architecture/phases/cross-cutting/dependency 五段结构与垂直切片标记。
+> 每个切片有 `<phase id="...">` 标识，供 TDD 工作流直接引用。
-## 切片列表
-[TODO: 用编号列表列出每个切片的标题、HITL/AFK 类型、依赖和覆盖的用户故事。]
+## 0. 一句话战略
+[TODO: 单句概括：做什么 + 为什么 + 怎么做到（新建/复用/以现有系统为基底）。]
-## 依赖顺序
-[TODO: 按可执行顺序列出切片，并说明阻塞关系。]
+## 1. 范围边界（IN / REUSE / OUT）
+[TODO: 三列表格。]
+| | 内容 |
+|---|---|
+| **IN 必造** | [TODO: 本次必造的新能力] |
+| **REUSE 复用现有** | [TODO: 复用不改动的现有能力] |
+| **OUT 本期不做** | [TODO: 留给后续迭代的内容] |
+## 2. 架构上下文
+[TODO: 涉及的模块与职责分工、新增模块定位、不可逾越约束。单文件修复可省略本节。]
+## 3. 切片
+### 切片 1 · [切片名称]
+<phase id="[phase-id]" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+- **类型：** AFK | HITL
+- **阻塞于：** 无
+- **覆盖：** [TODO: PRD 章节 / US 编号 / 用户故事]
+- **交付物：** [TODO: 具体文件/模块/功能]
+- **复用：** [TODO: 复用哪些现有能力]
+- **验收切片：** [TODO: 可独立执行的验证命令或步骤]
+- **对齐：** [TODO: PRD FR-xxx 或 issue 引用]
+- **ADR 引用：** [TODO: 关联的 ADR 编号，可选]
+### 切片 2 · [切片名称]
+<phase id="[phase-id]" status="未开始"><!-- 未开始 → 已实现(dev/03) → 已验证(dev/04) --></phase>
+- **类型：** AFK | HITL
+- **阻塞于：** 切片 1
+- **覆盖：** [TODO]
+- **交付物：** [TODO]
+- **复用：** [TODO]
+- **验收切片：** [TODO]
+- **对齐：** [TODO]
+- **ADR 引用：** [TODO]
+[TODO: 按需增加更多切片，每个有独立的 phase id]
+## 4. 横切关注点
+[TODO: 跨切片一致的规则与约束。]
+## 5. 依赖顺序速查
+```
+[TODO: ASCII 依赖链，如:
+P0  phase0-xxx  切片名称  ← 不可回退,最先
+P1  phase1-xxx  切片名称  依赖 P0
+]
+```
 ## 用户确认
-[TODO: 记录用户对粒度、依赖、HITL/AFK 标记和发布策略的确认。]
+[TODO: 记录用户对粒度、依赖、HITL/AFK 标记、phase id 和发布策略的确认。]
 ## 发布记录
 [TODO: 若发布到外部 issue tracker，记录 issue 引用；否则写明 local-only。]

package/speculo/workflows/dev/_templates/tdd-plan-template.md CHANGED Viewed

@@ -4,7 +4,7 @@
 # TDD Plan
 ## 阶段标识
-[TODO: 本阶段 `<phase-id>`。多阶段 roadmap 须与 roadmap `<phase>` 的 `id` 一致（如 `phase0-node-base`）；单阶段 change 用描述性切片 slug。产物落 `tdd/<phase-id>/`。]
+[TODO: 本阶段 `<phase-id>`。多阶段 slices 须与 slices `<phase>` 的 `id` 一致（如 `phase0-node-base`）；单阶段 change 用描述性切片 slug。产物落 `tdd/<phase-id>/`。]
 ## 切片来源
 [TODO: 记录来自 PRD、slices、diagnosis 还是用户直接请求。]

package/speculo/workflows/doc/00-INDEX.md CHANGED Viewed

@@ -14,6 +14,7 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 | 别名 | 入口 | 用途 |
 |------|------|------|
+| `doc/T` | `T-teach/T-teach.md` | 设计交互式课程：使命→资源→课程→参考→记录 |
 | `doc/F` | `F-writing-fragments/F-writing-fragments.md` | 追问式访谈，沉淀异质 fragment 素材 |
 | `doc/B` | `B-writing-beats/B-writing-beats.md` | 逐个 beat 推进文章旅程 |
 | `doc/S` | `S-writing-shape/S-writing-shape.md` | 读取素材堆并对话式塑造成文章 |
@@ -29,6 +30,7 @@ keywords: [doc, writing, article, fragments, edit, 文档, 写作]
 ## 执行模式
+- `teach`：想学某个主题，需要设计交互式课程体验，进入 `doc/T`。
 - `fragments`：从主题和对话中采集素材，进入 `doc/F`。
 - `beats`：已有素材，想逐个转向推进叙事，进入 `doc/B`。
 - `shape`：已有素材堆或粗稿，想塑造成可发布文章，进入 `doc/S`。

package/speculo/workflows/doc/T-teach/T-teach.md ADDED Viewed

@@ -0,0 +1,147 @@
+---
+id: doc/teach
+category: doc
+name: Teaching Design
+description: 设计交互式学习体验：确立使命、策展资源、构建术语、制作课程、记录洞察
+keywords: [teach, lesson, learning, glossary, 教学, 课程, 术语, 学习]
+---
+# Teaching Design 工作流执行指引
+本工作流用于在项目内围绕一个学习主题，设计并交付交互式教学体验。它是 `doc/T` 入口，覆盖从使命确立到课程产出、参考文档和洞察记录的完整链路。
+## 内置指引
+### 核心理念
+深度学习需要三样东西：
+- **Knowledge（知识）** — 从高质量、高信任度资源获取
+- **Skills（技能）** — 通过你设计的高度相关交互式课程获得
+- **Wisdom（智慧）** — 来自与其他学习者和实践者的互动
+获取知识时，难度是敌人——它会吃掉理解所需的工作记忆。练习技能时，难度是工具——有努力的提取才能建立长期留存。
+### 留存设计原则
+- **Retrieval practice**：让用户从记忆中回忆，而非重新阅读
+- **Spacing**：把练习分散到多节课，不要集中轰炸
+- **Interleaving**：在技能练习中混合不同但相关的主题
+每节课应该短小精悍，在很短时间内可完成。学习者工作记忆很有限，必须控制在容量内。但每节课应该给用户一个具体的小胜利。
+### 最近发展区
+每节课用户都应该感觉被挑战得「刚好够」。判断最近发展区的方法：
+1. 读取 `learning-records/`，了解用户已知什么
+2. 基于使命判断下一个该教什么
+3. 教能放进最近发展区的最相关内容
+### Lesson 铁律
+一节 lesson 是自包含的单个 HTML 文件，保存为 `.speculo/doc/<change>/lessons/<编号>.html`。它必须：
+- **漂亮** — 干净、可读的排版和布局，用户以后会回来复习
+- **短** — 在几分钟内可完成
+- **给一个胜利** — 每节课一个具体可感知的收获
+- **直接关联使命** — 每节课都追溯回 MISSION.md
+- **链向其他资源** — 通过 HTML 锚点链向其他课程和参考文档
+- **推荐一手资料** — 每节课推荐一个最高质量、最高信任度的外部资源
+- **提示提问** — 每节课包含提醒用户向 AI 教师追问
+### 课程结构模板
+```html
+<!DOCTYPE html>
+<html lang="zh-CN">
+<head>
+<meta charset="UTF-8">
+<title>课程标题</title>
+<style>
+  body { max-width: 680px; margin: 2rem auto; padding: 0 1rem; font-family: system-ui; line-height: 1.7; color: #1a1a1a; }
+  h1 { font-size: 1.6rem; margin-top: 2.5rem; }
+  blockquote { border-left: 3px solid #ddd; margin-left: 0; padding-left: 1rem; color: #555; }
+  .cite { font-size: 0.85rem; color: #888; margin-top: 2rem; border-top: 1px solid #eee; padding-top: 0.5rem; }
+  .reminder { background: #f5f5f5; padding: 0.8rem 1rem; border-radius: 6px; margin-top: 2rem; font-size: 0.9rem; }
+</style>
+</head>
+<body>
+<!-- 课程内容 -->
+<div class="cite">📖 推荐一手资料：<a href="...">资源标题</a></div>
+<div class="reminder">💡 有疑问？直接问我——我是你的 AI 教师。</div>
+</body>
+</html>
+```
+## 阶段
+> **产物目录：** 本工作流所有产物写入 `.speculo/doc/<change>/`。下文产物路径均相对该 change 目录。
+### 1. Mission Setup — 确立学习使命
+- 规范：`teach-mission.md`
+- 模板：`../_templates/teach-mission-template.md`
+- 产物：`mission.md`
+- 完成准则：
+  - 已追问出具体、可观测的成功标准（非「想了解 X」而是「能做 Y」）
+  - Why / Success / Constraints / Out of scope 四段均已填写
+  - `mission.md` 无残留 `[TODO:]`
+### 2. Resources Curation — 策展可信资源
+- 规范：`teach-resources.md`
+- 模板：`../_templates/teach-resources-template.md`
+- 产物：`resources.md`
+- 完成准则：
+  - 已搜集高信任度知识源（优先一手资料、公认专家、同行评审）
+  - 每条资源有注解：覆盖什么、何时取用
+  - 已找到至少一个可推荐社区（除非用户选择不加入社区）
+  - `resources.md` 无残留 `[TODO:]`
+### 3. Lesson Design — 设计一节交互式课程（主循环）
+- 规范：`teach-lesson.md`
+- 模板：无（HTML 课程见内置指引的课程结构模板）
+- 产物：`lessons/<编号>.html`
+- 完成准则：
+  - 课程短小（几分钟内可完成）、有一个具体胜利、直接关联使命
+  - 课程已链向相关参考文档和其他课程
+  - 课程包含一手资料推荐和 AI 追问提示
+  - 编号从已有最高编号 +1
+### 4. Lesson Wrap — 课程收尾
+- 规范：`teach-lesson-wrap.md`
+- 模板：`../_templates/teach-glossary-template.md`、`../_templates/teach-learning-record-template.md`
+- 产物：`reference/<编号>.html`、`GLOSSARY.md`（持续更新）、`learning-records/<编号>.md`（可选）
+- 完成准则：
+  - 已为该课程创建压缩参考文档（cheat sheet / 速查）
+  - 用户在本课中真正理解的术语已收录进 GLOSSARY.md
+  - 若产生非显而易见的洞察，已写 learning record
+  - 已更新 `NOTES.md`（若用户表达了教学偏好）
+## 依赖
+- 硬依赖：Phase 1 → Phase 2，使命未确立前不得策展资源
+- 软依赖：Phase 2 → Phase 3，建议先有资源再设计课程
+- Phase 3 ↔ Phase 4 为紧密循环：每节课程完成后立即收尾
+## 状态扩展字段
+本工作流需在同 change 的 `.status.json` 追加：
+- `doc_entry` (string) — 固定为 `doc/T`
+- `mission_status` (drafting | confirmed) — 使命确认状态
+- `resource_count` (number) — 已策展资源数量
+- `lesson_count` (number) — 已创建课程数量
+- `reference_count` (number) — 已创建参考文档数量
+- `learning_record_count` (number) — 已写学习记录数量
+- `glossary_term_count` (number) — 术语表条目数
+- `current_loop` (mission | resources | lesson | wrap) — 当前循环位置
+## 完成与状态更新
+- 进入每个 phase 时更新 `current_phase` 和 `phase_history`。
+- Phase 1 完成且用户确认使命后，`mission_status` 置为 `confirmed`。
+- Phase 3-4 为循环：每次完成一节课程和收尾后，更新 `lesson_count`、`reference_count`、`glossary_term_count`。
+- 每次捕捉到学习洞察时追加 `learning_record_count`。
+- 用户声明学习目标全部达成后，可把 `change_status` 置为 `completed`。
+- 如有可沉淀教学经验，在用户允许时追加到 `.speculo/.config/LESSONS.md`。
+- NOTES.md 作为教学偏好暂存区，AI 在后续课程设计中应参考其中记录。

package/speculo/workflows/doc/T-teach/teach-lesson-wrap.md ADDED Viewed

@@ -0,0 +1,63 @@
+# Lesson Wrap Phase
+本阶段在每节课程完成后立即执行，产出该课的压缩参考文档、更新术语表，并在产生非显而易见的洞察时写学习记录。
+## 输入
+- `.speculo/doc/<change>/lessons/<编号>.html` — 刚完成的课程
+- `.speculo/doc/<change>/GLOSSARY.md` — 已有术语表（若不存在则创建）
+- `.speculo/doc/<change>/learning-records/` — 已有学习记录
+- `.speculo/doc/<change>/NOTES.md` — 用户教学偏好
+## 产物
+- `.speculo/doc/<change>/reference/<编号>.html` — 本节课程的压缩参考文档
+- `.speculo/doc/<change>/GLOSSARY.md` — 更新后的术语表
+- `.speculo/doc/<change>/learning-records/<编号>.md` — 可选，仅当产生了非显而易见的洞察
+- `.speculo/doc/<change>/NOTES.md` — 可选，仅当用户表达了新的教学偏好
+## 填写引导
+### 创建参考文档
+1. 从刚完成的课程中提取最核心的内容——语法、算法、步骤、要点。
+2. 写成紧凑的 HTML 速查文档，设计上适合打印。干净排版，易扫读。
+3. 链接回原课程 HTML 和术语表中的相关条目。
+4. 参考文档是课程被复习时的入口——课程很少被重看，参考文档会。
+### 更新术语表
+1. 仅当用户在本课中**真正理解**了某个术语时才收录——术语表是压缩知识的记录，不是字典。
+2. 每条定义 1-2 句，说清术语**是什么**，不说它做什么或怎么做。
+3. 有多个同义词时选最佳者，其余标为「避免使用」。
+4. 术语表自身术语应互相引用——一旦一个术语入库，后续定义优先使用它。
+5. 用户理解加深时在原文上修订，不留过时条目。
+### 写学习记录（可选）
+仅当以下任一条件成立时写：
+1. 用户展示了非显而易见的真正理解
+2. 用户披露了先验知识（避免后续重新教）
+3. 一个误解被纠正（高价值：预测后续相关主题的绊脚石）
+4. 使命因学习而改变（更新 mission.md 并交叉引用）
+学习记录是精简的 ADR：1-3 句写清学到了什么以及为什么这会影响后续课程。编号从已有最高 +1。
+### 更新 NOTES.md
+若用户在本课中表达了教学偏好（如「我更想要视频」「不要太多术语」「多给练习」），记录到 NOTES.md 供后续课程设计参考。
+## 边界
+- 不写入用户尚未真正理解的术语。
+- 学习记录不记「已覆盖了某内容」——覆盖不等于学会。
+- 不重复术语表中已有的内容到学习记录中。
+## 完成准则
+- 参考文档已创建在 `reference/<编号>.html`
+- 用户本课真正理解的术语已收录进 `GLOSSARY.md`（或确认无需新增）
+- 若产生符合条件的学习洞察，已写 learning record
+- 若用户表达了新偏好，已更新 `NOTES.md`
+- `.status.json` 已更新 `lesson_count`、`reference_count`、`glossary_term_count`、`learning_record_count`

package/speculo/workflows/doc/T-teach/teach-lesson.md ADDED Viewed

@@ -0,0 +1,53 @@
+# Lesson Design Phase（主循环）
+本阶段是教学设计的核心循环。每次执行只设计**一节**课程，完成后进入 Phase 4 收尾，再回到本阶段设计下一节。
+## 输入
+- `.speculo/doc/<change>/mission.md` — 教学使命
+- `.speculo/doc/<change>/resources.md` — 可信资源
+- `.speculo/doc/<change>/GLOSSARY.md` — 已有术语（若存在）
+- `.speculo/doc/<change>/learning-records/` — 已有学习记录
+- `.speculo/doc/<change>/NOTES.md` — 用户教学偏好（若存在）
+- `.speculo/doc/<change>/lessons/` — 已有课程（判断最近发展区）
+## 产物
+- `.speculo/doc/<change>/lessons/<编号>.html`，按 `T-teach.md` 内置指引中的课程结构模板创建
+- 编号规则：扫描 `lessons/` 下已有最高编号 +1，起始 `0001`
+## 填写引导
+1. **判断最近发展区**：
+   - 读取已有 learning records 和 GLOSSARY.md，了解用户已知什么
+   - 基于使命中尚未覆盖的 Success 项，选择下一个该教的内容
+   - 教能放进最近发展区的最相关内容
+2. **知识先行，技能随后**：
+   - 课程前半段：从 resources.md 中的高信任度源提取知识，用最简洁的方式呈现
+   - 课程后半段：设计交互式练习或真实世界步骤，让用户实践
+   - 知识部分引用来源，每条声明有出处
+3. **设计反馈循环**：
+   - 如果是问答题，每个选项等长（避免通过格式暗示答案）
+   - 反馈尽可能即时、自动
+   - 练习的目标是建立 storage strength，不是 fluency
+4. **保持短小**：课程应在几分钟内完成。如果知识或练习过多，拆成多节。
+5. **关联使命**：课程开头一句话说明本节如何贡献于使命中的哪个 Success 项。
+6. **链向其他材料**：通过 HTML 锚点链向已有术语表、参考文档和相关课程。
+7. **每节课程末尾**：推荐一个一手资料（从 resources.md 中选取）+ 提示用户可追问 AI 教师。
+8. **创建后**：尝试自动打开 HTML 文件供用户查看。
+## 边界
+- 每次只设计一节课程，不批量预写后续课程。
+- 不编造知识——所有事实性声明必须来自 resources.md 中的资源。
+- 不假设用户记得上一节的内容——可以引用但关键概念要简要回顾。
+- 不在课程中加入超出使命范围的话题。
+## 完成准则
+- 课程 HTML 已创建在 `lessons/<编号>.html`
+- 课程短小（几分钟内可完成）
+- 课程包含知识部分（有引用来源）+ 技能练习部分（有反馈循环）
+- 课程关联使命中的具体 Success 项
+- 课程包含一手资料推荐和 AI 追问提示
+- `T-teach.md` 内置指引的课程铁律已全部满足

package/speculo/workflows/doc/T-teach/teach-mission.md ADDED Viewed

@@ -0,0 +1,33 @@
+# Mission Setup Phase
+## 输入
+- 用户声明的学习主题或模糊兴趣
+- 用户对「为什么想学这个」的任何初始表述
+- 当前 doc change 目录：`.speculo/doc/<change>/`
+## 产物
+- `.speculo/doc/<change>/mission.md`，由 `../_templates/teach-mission-template.md` 填写
+## 填写引导
+1. 若用户未给出具体目标，追问「你学这个最终想做到什么？」，直到得到可观测的行为描述——不是「了解 X」而是「能做 Y」。
+2. 从用户的回答中提炼 Why（1-3 句）、Success（具体可观测事项）、Constraints（时间/预算/偏好）、Out of scope（明确不做的话题）。
+3. 追问时保持具体：避免抽象框架，逼向真实世界的成果。
+4. 用户说不清时，继续访谈；坏使命比没使命更糟，但模糊使命也要被推回。
+5. 使命确立后与用户逐条确认，确认后才进入 Phase 2。
+## 边界
+- 不在此阶段搜集学习资源或设计课程。
+- 不编造用户的动机或目标——一切来自用户原话。
+- 使命可以后续修订，但修订必须经用户确认并写 learning record 记录变更原因。
+## 完成准则
+- Why / Success / Constraints / Out of scope 四段均已填写
+- 每条 Success 是可观测的、可判断是否达成的
+- 用户已逐条确认使命内容
+- `mission.md` 无残留 `[TODO:]`
+- 已创建 `NOTES.md`（空文件，用于后续记录教学偏好）

package/speculo/workflows/doc/T-teach/teach-resources.md ADDED Viewed

@@ -0,0 +1,36 @@
+# Resources Curation Phase
+## 输入
+- `.speculo/doc/<change>/mission.md`（已确认的使命）
+- 用户的社区偏好（是否愿意加入线上/线下社区）
+- 当前 doc change 目录：`.speculo/doc/<change>/`
+## 产物
+- `.speculo/doc/<change>/resources.md`，由 `../_templates/teach-resources-template.md` 填写
+## 填写引导
+1. **搜罗知识源**：针对使命中的每个 Success 项，搜寻高信任度资源。
+   - 优先：一手资料、公认专家著作、同行评审、强审核社区
+   - 避开：营销伪装成教育的内容、无引用的自媒体
+2. **注解每条资源**：用一句话写清覆盖什么、何时取用。裸链接三个月后无用。
+3. **分 Knowledge / Wisdom 两组**：
+   - Knowledge：书籍、文章、课程、论文——用于获取知识
+   - Wisdom：社区、论坛、线下课——用于获取智慧
+4. **标明缺口**：若某个 Success 项找不到好资源，在 `## Gaps` 段写明。
+5. **用户选择不加入社区时**，在 Wisdom 段记录此偏好，后续课程中不再推荐社区。
+## 边界
+- 不在此阶段设计课程。
+- 不因为资源少而编造或降级标准。
+- 不在 resources.md 中写课程计划或教学大纲。
+## 完成准则
+- 已针对使命中每个 Success 项搜集至少一条高信任度知识源（或在 Gaps 中标记缺失）
+- 每条资源有注解
+- 已找到至少一个可推荐社区（或记录用户拒绝社区）
+- `resources.md` 无残留 `[TODO:]`

package/speculo/workflows/doc/_templates/teach-glossary-template.md ADDED Viewed

@@ -0,0 +1,25 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `GLOSSARY.md`
+# [TODO: 学习主题] Glossary
+[TODO: 1-2 句描述本术语表覆盖的主题范围。]
+## Terms
+[TODO: 每个术语 1-2 句，说清它**是什么**，不说它做什么或怎么做。术语表自身术语互相引用。]
+**[TODO: 术语名]**：
+[TODO: 定义——术语是什么。]
+_Avoid_: [TODO: 列出应避免的同义词或不当用语]
+**[TODO: 术语名]**：
+[TODO: 定义。]
+_Avoid_: [TODO: 不当用语]
+## Rules
+- 仅在用户**真正理解**术语后才收录——术语表是压缩知识的记录，不是字典。
+- 有自己的观点：当多个词指向同一概念时，选最佳者，其余标为避免使用。
+- 定义内部使用术语表自身的术语——一旦入库，后续定义优先使用它。
+- 理解加深时在原文上修订，不留过时条目。
+- 若某术语在更广领域中用法模糊，注明本 workspace 内的约定用法。

package/speculo/workflows/doc/_templates/teach-learning-record-template.md ADDED Viewed

@@ -0,0 +1,37 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `learning-records/<编号>.md`
+学习记录使用顺序编号：`0001-<slug>.md`、`0002-<slug>.md`。首次写入时创建目录。
+每一条是精简的 ADR：1-3 句写清学到了什么以及为什么这会影响后续课程。编号从已有最高 +1。
+## 模板
+```markdown
+# [TODO: 简短标题——学到了什么或建立了什么认知]
+[TODO: 1-3 句。学到了什么（或建立了什么先验知识），以及为什么这会影响后续课程。]
+```
+## 何时写
+仅在以下任一条件成立时写：
+1. **用户展示了非显而易见的真正理解** — 不是仅仅接触过，而是有证据表明能正确使用这个概念。这为后续教学设定了新底线。
+2. **用户披露了先验知识** — 「我已经知道 X」。记录下来避免后续重新教。同时记录声称的深度。
+3. **一个误解被纠正** — 用户之前相信了错误的东西，现在明白了为什么。高价值：预测后续相关主题的绊脚石。
+4. **使命因学习而改变** — 用户发现自己在意的和最初想的不同。交叉引用 [[mission.md]] 并更新它。
+### 不写的情况
+- 仅仅覆盖过的内容。覆盖 ≠ 学会。等证据。
+- 已被 GLOSSARY.md 精简收录的术语定义。不重复。
+- 逐节课的活动日志。学习记录不是流水账——是决策级的洞察。
+## 可选节
+仅在真正增值时加入：
+- **Status frontmatter**：`active | superseded by LR-NNNN` — 当早期理解被后续认知推翻时使用。
+- **Evidence**：用户如何展示理解（回答的问题、完成的练习、引用的先验经历）。
+- **Implications**：这对后续课程解锁或排除了什么。

package/speculo/workflows/doc/_templates/teach-mission-template.md ADDED Viewed

@@ -0,0 +1,18 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `mission.md`
+# Mission: [TODO: 学习主题]
+## Why
+[TODO: 1-3 句。用户追逐的具体真实世界目标。学会这个之后，他们的生活或工作中会发生什么改变？避免「想了解 X」这类抽象表述——逼向底层成果。]
+## Success looks like
+- [TODO: 一个具体的、可观测的用户将能做到的事项]
+- [TODO: 另一个具体事项]
+- [TODO: …]
+## Constraints
+- [TODO: 时间、预算、先验承诺、学习偏好——任何限定教学方式的约束]
+## Out of scope
+- [TODO: 用户明确不想现在涉及的相邻话题——保护最近发展区]

package/speculo/workflows/doc/_templates/teach-resources-template.md ADDED Viewed

@@ -0,0 +1,17 @@
+> **服务工作流：** `../T-teach/T-teach.md`
+> **产物文件名：** `resources.md`
+# [TODO: 学习主题] Resources
+## Knowledge
+- [TODO: 格式：`[类型: _标题_ — 作者（出处）](链接)`，下一行缩进写用途。优先一手资料、公认专家、同行评审。]
+  [TODO: 覆盖什么、何时取用。]
+## Wisdom (Communities)
+- [TODO: 格式同 Knowledge。线上论坛、线下课、本地兴趣小组。]
+  [TODO: 用于什么场景的反馈或讨论。]
+## Gaps
+[TODO: 若某 Success 项找不到好资源，在此列出。用户选择不加入社区时也在本节记录。]