--- name: eo-change-review description: | 对 change.md 做方案级审查（AC 质量、TODO↔AC 映射、粒度合规、意图一致性）。触发：审查 change / change 审查 / 审方案 / /eo-change-review。 NOT FOR: 代码审查（/eo-review）、implement 内的回归审查。 --- # eo-change-review — Change 方案审查 对一个 change 做方案级审查，在 implement 前把牢「方向是否正确、AC 是否可验收、TODO 是否完整、粒度是否合规」。**可选环节**——小 change 可跳过；AC ≥5 条 / 含 §5 技术方案 / type=refactor / 高风险 change 建议跑。 ## 与另一种 review 的关系 | Skill | 审查对象 | 问的问题 | |-------|---------|---------| | **`eo-change-review`**（本技能） | 某个 change 的 `change.md` | 方案对不对？AC 质量、TODO 完整性？ | | `eo-review` | change 实施后的代码 | 代码对不对？实现 vs AC？ | 两者关注点、上下文、回退动作完全不同，**不要混用**。 ## 核心原则 1. **方案级审查，不替作者做决定**：只产出报告，修订由用户回 `/eo-change` 执行 2. **AC 是重中之重**：change 的价值密度集中在 §2 验收清单；AC 不可验收，后面全白做 3. **不审实施质量**：此时代码还没写，不审代码质量；但维度 7 的**前提校验落到真实代码**——state 文档可能过期，读码取证不等于审码 4. **固定产出**：`eo-doc/changes//change-review.md` 5. **采样式质检，不是穷尽式收敛**：只有 P0 阻塞流程，P1 移交起草方裁决；复审默认增量核销，不重开全文；累计上限 3 轮，到限升级用户裁决 ## 前置条件 - **必须能找到 `.eo-project.json`**。同目录存在 `.eo-project.local.json` 时顶层字段覆盖合并（local 优先）。找不到 → 报错退出，提示运行 `/eo-project-init` - `eo-doc/changes//change.md` 存在，status 为 `draft` 或 `confirmed`（implementing 及之后 → 提示应走 /eo-review） ## 工作流程 ### 第零步：轮次与模式判定 - **首轮**（目录下无 change-review.md）：全量审查 - **复审轮**（已有 change-review.md）：默认**增量**。命中下表任一信号（机械可判，不做主观裁量）→ 自动升级**全量**并向用户播报命中哪条；用户显式指定模式时以用户为准，优先于自动判定 | 升级信号 | 为什么 | |---------|--------| | AC 有增删，或既有 AC 语义性改写（非措辞微调） | AC 是映射与覆盖检查的锚，锚动则增量核对失效 | | §1 已钉决策变动 | 意图层变化使上轮一致性结论作废 | | 修订触及超过 1/3 的 TODO，或修订量超全文 30% | 波及面超出定点核对范围 | | finding 台账或处置落点缺失（如跨会话丢上下文） | 增量输入不存在，全量兜底 | - **全量复审 ≠ 从零**：台账中 `wont-fix` 项在任何轮次、任何模式下豁免，不得重报 - **轮数纪律**：复审累计上限 **3 轮**（升级全量不重置计数）；到限仍有未决 P0 → 停止循环，把未决项列给用户裁决（终态措辞见第四步） - **revision 边界**：轮数与 wont-fix 豁免均以 change.md frontmatter `plan_revision`（缺省视为 1）为界——回炉进入新 revision 后轮数从 1 起算、旧 revision 的 wont-fix 失效（新方案下可重报）；新 revision 首轮按全量跑，报告在「速报」前另起 `## Revision R 审查` 分段，旧 revision 内容冻结不改 ### 第一步：阅读上下文 **tier: light 的 change 不适用本 skill**（轻档方案审查由探针对齐替代，见 [../eo-shared/granularity.md](../eo-shared/granularity.md) §5）——提示直接 `/eo-implement` 轻模式。 **全量（首轮 / 升级）**： 1. 读目标 change.md 全文（v2 模板：§1 意图 + 已钉决策、§2 AC、§3 TODO、条件节 §4-§8） 2. 读 `eo-doc/changes/INDEX.md` 最近 3 条（避免与在途/已归档 change 冲突或重复） 3. 读 `eo-doc/state/` 相关篇目（系统现状，校验变更前提） 4. frontmatter `type` 缺失或不在枚举（bootstrap/feature/enhance/refactor）→ 直接 P0 报告，**不向用户追问类型归属** 5. 复审轮另加：读 finding 台账，继承 `wont-fix` 豁免与已核销记录 **增量复审**： - **同会话**：上轮 finding 与修订过程已在上下文，**不重读任何文件**，直接进入核销 - **跨会话**：读 change-review.md（台账 + 上轮报告）→ 按台账「处置」列的改动落点**定点读** change.md 对应段落，不读全文 ### 第二步：系统审查 **增量复审只做两件事**，不重开全文： 1. **核销**：逐条验证台账未决 P0/P1 的修复——按处置落点核对，改到位 → `verified`；没改到位 → 保持 `open` 并一句话说明 2. **审增量**：只对本轮修订引入/改动的内容找新 finding。**新 finding 必须能指认「由本轮修订引入」，否则无效**——首轮就该发现的问题不允许复审轮补报（对审查采样噪声的抑制闸） **全量审查**跑满以下 7 维度： - **维度 1 · AC 质量（最关键）**：对照 [../eo-shared/ac-spec.md](../eo-shared/ac-spec.md) 逐条检查——用户视角？可独立验证（声明 + 验证栏合读能得出怎么操作、看什么；验证栏按增量制省略不算缺）？技术无关且可度量（无「正常工作」类主观词）？覆盖异常路径（至少 1 条失败/边界 AC）？refactor 类是否写了「行为不变」的回归口径？ - **维度 2 · TODO↔AC 映射**：每条 TODO 标注了对应 AC 且映射成立？每条 AC 至少被一条 TODO 覆盖？出现映射不到 AC 的 TODO（越界）或没有 TODO 的 AC（悬空）→ P0 - **维度 3 · TODO 拆解质量**：三要素齐全（描述/文件/对应 AC）？多条 TODO 对同一 AC 时是否逐条写了完成判据（一对一不要求）？**占位符检测**（「补充错误处理」「后续完善」→ P0）？Batch 分组合理、Batch 1 是可独立验证的 MVP？依赖自洽无循环？**并行组核验**（存在字母后缀批时）：同层批文件集相交，或存在逻辑依赖（一批消费另一批的接口/数据结构，[../eo-shared/granularity.md](../eo-shared/granularity.md) §6）→ P1（并行不安全，建议去后缀转串行） - **维度 4 · 粒度合规**：对照 [../eo-shared/granularity.md](../eo-shared/granularity.md)——TODO 数与全文行数在软标内（超软标 P1 建议拆、超硬标 P0 必须拆）；反向检查：是否 trivial 到根本不该开 change（→ P1 建议转直改） - **维度 5 · 意图一致性**：§1 已钉决策与 §2/§3 是否自洽（TODO 有没有偷偷推翻已钉结论）？`type` 与实际内容匹配（宣称 refactor 却新增用户可见能力 → 应改 feature）？混入多个不相关改动 → 建议拆；AC/TODO 是否超出 §1 意图自行扩面（镀金，见 [../eo-shared/ac-spec.md](../eo-shared/ac-spec.md)「不镀金」）→ P1 建议裁剪或转 backlog；**速览一致性**：速览缺失、行为差异与 §1/§2 冲突、或复述 AC 条文而非用户可见差异 → P1 - **维度 6 · 条件节合规**：触发条件满足却缺节（有 TODO 未覆盖的连带文件但无 §4；有新外部依赖但无 §5；有不可逆操作但无 §7）→ P1；触发条件不满足却写了 → P2（瘦身建议）；§8 defer 超过 3 条 → P1；change 含 §6 流程图时对照 [../eo-doc-manager/references/mermaid.md](../eo-doc-manager/references/mermaid.md) §5 审查清单核对 - **维度 7 · 前提真实性抽查**：方案前提落到**真实代码**核验（state 文档可能过期，不能只对文档校验）—— - **机械核验**（全量跑，不占抽样名额）：§3 每条 TODO 按文件栏操作类型分型核验——`新增:` 查父目录/模块惯例/命名冲突；`修改:`（含缺省）查对象存在与形态相符；`删除:` 查对象存在与引用面 - **高风险前提抽样**：候选池 = §1/§4/§5/§7 中对现状事实、兼容性、唯一性、外部契约的断言；按不可逆性 > 数据/权限风险 > 跨模块面排序取 **2-3 条**定点读码核验。每条前提标基线：「变更前事实」审 `base_commit`（首轮审查时即 HEAD；回炉复审用 `git show :`——防被上一轮实施在 HEAD 造出的代码自证）；「当前兼容性」读 HEAD + 本 change 未提交 diff - 报告固定四栏：断言 / 基线 / 证据（file:line 或命令输出）/ 判定。**前提不成立 → P0（必须附直接证据）；证据不足 → P1 要求补证，不猜 P0** **定级纪律（全模式通用）**： - **P0 只收客观可判项**：TODO↔AC 映射断裂 / 占位符 / 粒度超硬标 / AC 不可验证（声明与验证栏合读仍不知怎么验）/ type 缺失或不在枚举 / TODO 推翻已钉决策 / **前提不成立（维度 7，附直接证据）**。程度与取舍类判断（粒度软标、条件节取舍、表述质量、意图一致性的程度问题）最高 P1 - **不确定就降级**：拿不准 P0 报 P1，拿不准 P1 报 P2；每条 P0/P1 必须落到具体位置（§X / 条目号）并附可执行修复建议，给不出的不报 ### 第三步：撰写报告 - **首轮**：按下方模板写入 `eo-doc/changes//change-review.md`（含 Finding 台账） - **复审轮**：**不重写报告**——只更新台账状态列，在「速报」节之前追加一节 `## 复审记录（第 N 轮 · 增量/全量 · YYYY-MM-DD）`（核销结果 / 新增 finding / 未决清单），并原地更新「速报」节。「速报」必须始终是文件末节（编排方按"末尾速报"取下一步） ### 第四步：对话速报（硬性——缺速报 = 流程未完成） ``` 结论：通过 / 不通过（P0 x 条）［第 N 轮 · 全量/增量］ P0（阻塞 implement）： 1. <一句话> — change.md §X P1（移交起草方裁决，不阻塞循环）： 2. <一句话> — change.md §X P2（可后置）： 3. <一句话> 下一步：<见下方终态措辞> （详细分析见 ） ``` 终态措辞**三选一，严禁混用**： - **通过（P0=0）**：「下一步 `/eo-implement `（status 若仍为 draft，先回 /eo-change 对话确认）。未决 P1 已入台账，由起草方裁决：采纳的回 /eo-change 顺手修（**不触发复审**），不采纳的标 wont-fix 附理由。注意：`/eo-review` 是代码审查，要在 implement 之后，现在还不轮到它。」 - **需修订（P0>0 且未到 3 轮）**：「回 `/eo-change ` 逐条处置：修复的在台账标注改动落点，不认同的标 wont-fix 附理由；然后再跑 `/eo-change-review` 复审（默认增量，锚变动自动升全量），循环到 **P0=0**。当前第 N/3 轮。🚫 不要跳过复审直接 implement，不要跑 /eo-review（代码还没写）。」 - **到限（第 3 轮仍有未决 P0）**：「复审已达 3 轮上限，停止循环。未决 P0：<清单>。请裁决：a) 显式豁免并放行 implement（豁免记录入台账与 change.md §8） b) 指定修复后仅做一次核销复审 c) 回炉重做 change。」 ## 固定模板 — change-review.md ```markdown --- title: <标题> Change 审查报告 change_id: created: YYYY-MM-DD status: active summary: > 一句话审查结论。 --- # <标题> Change 审查报告 > 关联：[change.md](change.md) ｜ 审查日期：YYYY-MM-DD ｜ change status：draft / confirmed ## 审查总结 一段话 + 明确结论：✅ 可进入 implement / ⚠️ 小幅修订后进入 / ❌ 需大幅修订 ## Finding 台账 | ID | 级别 | 摘要 | 位置 | 状态 | 处置（修订方填） | |----|------|------|------|------|------------------| | P0-1 | P0 | <一句话> | §3 | open / fixed / verified / wont-fix | <改动落点 或 wont-fix 理由> | ## P0 - 必须修订（阻塞 implement） ### [P0-1] <标题> - 类型：AC 不可验收 / 映射断裂 / 占位符 / 粒度超硬标 / 类型错配 - 位置：change.md §X ｜ 描述 ｜ 影响 ｜ 建议 ## P1 - 建议修订（移交起草方裁决，不阻塞） ### [P1-1] <标题>（类型：粒度超软标 / 条件节缺失 / 异常路径未覆盖 / defer 超限…） ## P2 - 可选优化 ## AC 质量检查 | AC | 用户视角 | 可验证 | 技术无关 | 备注 | |----|---------|--------|---------|------| ## TODO↔AC 映射检查 | TODO | 对应 AC | 状态 | |------|---------|------| | TODO-1 | AC-1 | ✅ / ⚠️ / ❌ | ## 粒度检查 TODO 数：N（软标 3-7 / 硬标 10）｜ 全文：N 行（软标 500 / 硬标 700）｜ 结论：合规 / 建议拆 / 必须拆 ## 前提真实性抽查（维度 7） | 断言 | 基线 | 证据 | 判定 | |------|------|------|------| | <一句话前提> | base_commit / HEAD | `file:line` 或命令输出 | ✅ 成立 / ❌ 不成立 / ⚠️ 证据不足（P1 补证） | ## 结构完整性 | 节 | 状态 | 备注 | |----|------|------| | 速览 | ✅/⚠️/❌ | 人读投影与 §1/§2 一致 | | §1 意图 + 已钉决策 | ✅/⚠️/❌ | | | §2 验收清单 | ✅/⚠️/❌ | | | §3 TODO（Batch） | ✅/⚠️/❌ | | | 条件节 §4-§8 | ✅/⚠️/❌ | 触发条件 vs 实际取舍 | ## 复审记录（第 2 轮 · 增量 · YYYY-MM-DD） - 核销：P0-1 verified（<落点一句话>）；P1-1 wont-fix（<理由>） - 新增：无 ／ P0-2 <一句话>（由本轮修订引入：<指认>） - 未决：无 → 结论：通过 ## 速报 结论：通过 / 不通过（P0 x）［第 N 轮 · 全量/增量］ 下一步：（通过）status 为 draft 时先回 /eo-change 完成确认 → /eo-implement / （需修订）回 /eo-change 处置后复审（第 N+1/3 轮） / （到限）交用户裁决 ``` 末尾「速报」节必填——它是报告的机器可读出口（编排方读文件即取下一步），与第四步对话速报同款内容。 ## 关键约束 - **不改 change.md**：只产报告，修订归 `/eo-change` - **P0 精准且客观**：只有阻塞 implement 的客观可判问题才 P0（白名单见第二步定级纪律）；不确定就降级 - **只有 P0 阻塞循环**：P1 移交起草方裁决，P1 的修复不触发复审 - **复审不重开全文**：增量为默认；复审轮新 finding 必须指认由本轮修订引入；wont-fix 项永不重报 - **报告追加不覆盖**：复审只更新台账 + 追加复审记录，上轮报告原文保留 - **轮数上限 3 轮**：升级全量不重置计数，到限交用户裁决 - **不审实施质量**（代码质量归 /eo-review；维度 7 读码仅为前提取证）、不审业务方向本身（方向的家在 brainstorming/意图确认） - **避免触发钩子噪声**：报告中避免使用「关键决策」等字样（可能触发上游配置的记录钩子），用「设计判断」「模式选择」代替 - **可操作**：每个问题的建议必须具体到用户能直接行动