@xulthekl/team-flow 0.60.0 → 0.62.0

package/docs/plans/2026-09-21-001-three-optimization-eval.md

@@ -0,0 +1,127 @@
+# 三个工作流优化点 · 设计评估笔记
+
+> 日期：2026-09-21
+> 遵循流程：`CONTRIBUTING.md`「Large Changes」——重大工作流变更先写 design note，再同步改 skills / templates / examples。
+> 本文档为**评估稿（第一步）**：评估现状、缺口、影响面、可行性与建议方案。实施待评估通过后再落地。
+
+## 0. 评估结论速览
+
+| # | 优化点 | 现状 | 缺口 | 可行性 | 实施强度 |
+|---|--------|------|------|--------|----------|
+| 1 | 决策话术人类化（避免太技术） | DP 门禁集中定义于 `docs/decision-points.md`，但提问文案由各 skill 的 AskUserQuestion 自定，无"白话"硬规则 | 选项 label/description 含术语（执行模式 SDD/Inline、聚合/限界上下文/CQRS），非技术用户看不懂 | 高（纯文案/规则层，不动状态机） | 改 `decision-points.md` + 各含 DP 的 skill 文案 |
+| 2 | bugfix 匹配源头 change 快速修复 | 执行期 bug 走 `workflow-start → bug-investigator`（debugging 侧路径）；S1 有 Hotfix 入口。但**无"bug 回溯到引入它的源 change"机制** | 发现 bug 时无法复用源 change 的 scope/AC/design/tests 上下文，每次从零确认 | 中（新增 `source_change` 字段 + 匹配检索 + 轻量修复路由，复用 hotfix/tweak 通道） | 改 S1 + workflow-start + bug-investigator + change-brief 模板 + state schema |
+| 3 | change 拆分原则明确定义，不建议拆太细 | `change-split-auditor` D5（所有权自包含，v0.9 根因判据）已防"切碎"FAIL；D3 粒度"太小"仅 Important（advisory）；`ce-plan/references/change-splitting.md` 有完整判据 | 缺**显式默认姿态**："宁粗勿细，只有越过所有权边界才拆"。文档是判据（什么算坏），不是原则（默认怎么拆） | 高（文档/判据层微调） | 改 `change-splitting.md` + `change-split-auditor` D3 权重 |
+
+---
+
+## 1. 优化点①：决策话术人类化
+
+### 1.1 现状
+- 所有需要用户拍板的节点集中在 `docs/decision-points.md`（DP-0 ~ DP-7），由各 skill 通过平台阻塞问题工具（AskUserQuestion）发起。
+- 现有话术规范只管**流程**（need-explorer「一次一问」「给 2-3 个选项带取舍」「先复述确认」），**不管话术的"技术浓度"**。
+- 术语直灌选项，非技术 PM / 业务方看不懂，例如：
+  - DP-4「执行模式选择」：`propose waves` / `SDD` / `Inline` / `Batch Inline`（机制词进 label）。
+  - DP-A「架构产品确认」：`聚合` / `限界上下文` / `CQRS` / `读模型`（架构术语无白话等价）。
+  - S1 路径路由：`续版需求` / `重新计划` / `单 change 快速通道`（行话，未解释"选了会怎样"）。
+
+### 1.2 缺口（需新增的硬规则）
+1. **可见文案用"人话"**：用"结果/价值"描述而非"机制"；术语首次出现必须括注白话等价（如 `聚合（一组相关的业务数据，比如一张订单及其明细）`）。
+2. **选项口吻**：以"你选哪个"的口吻；label ≤ 12 字；description 讲"选它会怎样"，不写"这是什么"。
+3. **术语下沉**：SDD / Inline / 契约 / 聚合等技术细节沉到 description 或折叠区，**不进 label**。
+4. **定位**：决策点是"帮你拍板的岔路口"，不是考试——避免让用户做他没能力判断的技术选型。
+
+### 1.3 影响面（需 audit 的 DP 文案）
+- `need-explorer`（DP-1）、`workflow-start`（DP-0 / G4 同步 / DP-4 / DP-6 / DP-7）、`contract-builder`（DP-3）、`architecture-design`（DP-A）、`ce-plan` / `ce-brainstorm`（模式选择）、`workflow-orchestrator`（S1 路由、S4 G5 同步）、`prototype`（决策点中继）。
+- 落点：`docs/decision-points.md` 新增「话术规范」一节 + 上述 skill 的提问 prompt 文案。
+
+### 1.4 方案与风险
+- 方案：新增一处统一话术规范（原则 + 正反例），并 audit 现有所有 DP 文案，改写为白话版；术语保留在 description 内以保证精度。
+- 风险：过度口语化可能损失精度 → 用"label 白话 + description 含术语"分层化解。可行性高，不动状态机。
+
+---
+
+## 2. 优化点②：bugfix 匹配源头 change 快速修复
+
+### 2.1 现状
+- 执行期 bug：`workflow-start`「Route to bug-investigator」→ `executing → debugging` 侧路径 → 回 `build-executor`。`bug-investigator` 是纯科学根因调查，**不认 change 来源**。
+- 产品级：`workflow-orchestrator` S1「紧急修复（Hotfix）」入口 → 直接建 change（`type:hotfix`，注入 bug 描述替代 PRD）→ `workflow-start`，closing 强制补录复利。
+- **关键缺口**：无论执行期还是线上发现的 bug，都**没有"把缺陷回溯到引入它的源 change"的机制**。无法复用源 change 的 `change-brief` / `design.md` / `specs/` / `tests` / `learnings.md` 上下文，每次都从零确认修复 scope。
+
+### 2.2 方案建议（新增"bugfix 快速修复"模式）
+1. **触发**：用户报 bug / 线上问题 / 已 closing change 暴露缺陷（独立于 Hotfix）。
+2. **匹配源 change**：
+   - `git blame` + 受影响文件/符号 → 定位引入 commit → 经 `change_dag` / `change-brief` / `learnings.md` 反查 `change_dir`；
+   - 或按受影响 capability 在全局 `specs/` 检索归属 change。
+3. **快速修复路由**：
+   - **命中源 change** → 复用其 `change-brief` / `design.md` / `specs` 作"已知设计约束"上下文，走轻量修复（tweak / hotfix 形态，但带 `source_change` 引用字段），省去重复 scope 确认。
+   - **非命中**（独立缺陷 / 新文件）→ 走现有 Hotfix。
+4. **字段与产物**：
+   - `workflow-start` 状态文件新增 `source_change` 字段；新增 `reopen` / `quick-fix` 路由（reopen 仅限用户确认，绝不静默）。
+   - `bug-investigator` 报告新增「源 change 关联」段（命中则填 change_dir + 复用约束）。
+
+### 2.3 影响面
+- `workflow-orchestrator` S1（增强/新增 Hotfix 判据，叠加"是否命中源 change"分支）。
+- `workflow-start`（新增 `source_change` 字段 + reopen/quick-fix 路由 + Guardrails）。
+- `bug-investigator`（报告模板加溯源段）。
+- `changes/<name>/change-brief.md` 模板（加 `source_change_ref` frontmatter）。
+- `src/schema/change.ts` 状态 schema + `docs/artifact-contract.md`。
+
+### 2.4 可行性与风险
+- 可行性：中。核心是"源 change 关联"检索，可基于既有 `git blame` + change 元数据（已有 `change_dag` / `change-brief`）。复用 hotfix/tweak 快速通道，不新造状态。
+- 风险：`git blame` 关联可能失准（重构 / 多 change 共改一行）→ **必须让用户确认匹配结果**，不做静默自动 reopen；匹配失败时优雅降级到 Hotfix。
+
+---
+
+## 3. 优化点③：change 拆分原则明确定义，不建议拆太细
+
+### 3.1 现状
+- `change-split-auditor` D5（v0.9 根因判据·所有权自包含）：≥2 change 瓜分同一聚合/上下文/读模型/契约 → **FAIL（切碎）**；细到无设计单元 → **FAIL**；跨无关节所有权单元 → **FAIL**。
+- D3 粒度均衡：`太大 → Important（建议拆）`；`太小 → Important（建议合）`，**advisory，不单独 FAIL**。
+- `ce-plan/references/change-splitting.md`：完整所有权判据 + Good/Anti-Patterns + Depth Guidance（Standard 2-5 个 change）。
+
+### 3.2 缺口
+- 现有内容是**判据（什么算坏）**，不是**原则（默认怎么拆）**。用户/ce-plan 在"可拆可不拆"时缺一条**显式默认姿态**："宁粗勿细——只有越过所有权边界、或需要独立并行验证、或需要团队分别领取时，才向下拆细"。
+- D3「太小」仅 Important 不阻断，倾向多拆时 auditor 不拦；需把"拆太细"的代价上升为**默认原则**。
+
+### 3.3 方案建议
+1. `change-splitting.md` 顶部显式声明**默认拆分姿态**（粗粒度优先三条件：越过所有权边界 / 可独立并行验证 / 团队领取需要——三者任一成立才拆细）。
+2. `change-split-auditor` D3 提升"太小"信号权重：当单 PRD 的 change 数超过中等规模上限（如 Standard > 5）时，auditor 主动建议合并并给出合并候选；在 Depth Guidance 写"粗粒度优先"。
+3. 明确"拆太细"的代价：每个 change 走完整 8 态 + 4+1 产物 + 架构增量 + 复利回写，ceremonies 开销 > 价值（现有 anti-pattern 已提，上升为默认原则）。
+
+### 3.4 可行性与风险
+- 可行性：高（文档/判据层微调，不动状态机）。风险低。
+
+---
+
+## 4. 按 plugin 流程的后续实施路径
+
+> 本笔记评估通过后，依 `CONTRIBUTING.md` 同步改 skills / templates / examples：
+
+1. **设计笔记**：本文（已完成评估）。
+2. **话术规范**：`docs/decision-points.md` 新增「话术规范」节 + audit 改写各 DP 文案（优化点①）。
+3. **bugfix 模式**：S1 + workflow-start + bug-investigator + change-brief 模板 + state schema（优化点②）。
+4. **拆分原则**：`change-splitting.md` + `change-split-auditor` D3（优化点③）。
+5. **tests**：`npm test` 过 frontmatter-lint；补「决策话术白话」自检 / change-split 粗粒度优先用例（如需要）。
+6. **CHANGELOG.md**：记录三处用户可见变更。
+7. **examples**：必要时更新 `docs/examples/` 中 bugfix / 粗粒度拆分样例。
+
+## 5. 开放问题（待大哥拍板）
+
+## 6. 决策记录（大哥拍板，2026-09-21）
+
+| # | 开放问题 | 决策 | 落地影响 |
+|---|---------|------|---------|
+| ② | 新增独立 bugfix 入口 vs 增强现有 Hotfix | **增强现有 Hotfix**（改动小） | S1 Hotfix 入口内叠加"是否命中源 change"分支；不新增独立入口 |
+| ① | 全 DP 改双行 vs 仅关键 DP | **最小改动：在两个入口 skill 内各加一小段「话术规范」定义**（workflow-orchestrator + workflow-start） | 不逐个改 subagent skill；入口 skill 设标准，subagent 提问沿用同一口径（need-explorer/ce-plan 等后续可引用，非本次强制） |
+| ③ | D3「太小」升 Critical vs 加强建议 | **只建议、不硬拦**（2026-09-21 拍板） | 保持 advisory；声明"粗粒度优先"原则 + 审计员主动建议合并，不升 Critical |
+
+### 6.1 据此锁定的实施方案（待 ③ 拍板后一并实施）
+
+- **优化点①（最小改动）**：在 `workflow-orchestrator/SKILL.md` 与 `workflow-start/SKILL.md` 各新增一节「决策话术规范」（label 白话 + description 含术语；术语首现括注白话等价；选项口吻"你选哪个"；决策点=帮拍板的岔路口）。同步在 `docs/decision-points.md` 顶部加"话术规范"引用锚点。
+- **优化点②（增强 Hotfix）**：
+  - `workflow-orchestrator` S1 Hotfix 入口：用户报 bug 时，先尝试 `git blame` + change 元数据反查源 change；命中则在建 change 时携带 `source_change` 引用，非命中走原 Hotfix。
+  - `workflow-start` Hotfix 路由：新增 `source_change` 字段消费 + "复用源 change 上下文做轻量修复"说明 + Guardrail（匹配结果必须用户确认，失准降级 Hotfix，绝不静默 reopen）。
+  - `bug-investigator` 报告模板：新增「源 change 关联」段。
+  - `changes/<name>/change-brief.md` 模板：`source_change_ref` frontmatter（可选）。
+  - `src/schema/change.ts` 状态 schema：新增 `source_change` 字段（additive）+ `docs/artifact-contract.md` 记录。
+- **优化点③（待 ③ 拍板）**：`change-splitting.md` 顶部声明"粗粒度优先"原则；`change-split-auditor` D3 主动建议合并（不升 Critical）。