eo-spec-review

name	eo-spec-review
description	对模块 spec.md 做系统性质量审查。必需场景：module-init 阶段（由 /eo-module-init 触发一次）。可选场景：archive 后含大量 MODIFIED/REMOVED 时复检。触发：审查 spec / review spec / 检查需求 / /eo-spec-review。 NOT FOR: 审代码（/eo-review）或 change 方案（/eo-change-review）。

eo-spec-review — 模块 spec 审查

对模块 spec.md 做系统性质量审查，确保模块基线完整、无歧义、可执行。

适用阶段：

• 强制一次：模块初始化时（由 /eo-module-init 自动触发）
• 可选复检：archive 后 spec 被 Delta 大改、或发生结构性 refactor 后，用户主动触发

日常业务变更不需要跑 spec-review（走 /eo-change 写 Delta + /eo-change-review 即可）。

核心原则

1. 对照模板审查：严格依据 spec 模板检查每个章节的完整性与质量
2. 发现歧义：识别所有可能导致 plan/implement 阶段产生分歧的模糊描述
3. 不改 spec：审查只产出报告，修订工作由用户决定后通过 /eo-spec 执行
4. 固定产出：输出到 eo-doc/dev/<module-name>/spec-review.md

模板发现

启动时检查 eo-doc/templates/：

• 若 eo-doc/templates/project-profile.md 存在 → 读取，了解项目类型和层级结构
• 若 eo-doc/templates/spec-layers.md 存在 → 读取，作为维度 7 "多层协作完整性"的审查依据（知道模板要求了什么，才能判断 spec 是否完整）
• 若上述文件不存在 → 跳过维度 7（现有默认行为）

前置条件

• 必须能找到 .eo-project.json。找不到 → 报错退出，提示运行 /eo-project-init。eo-doc/ 路径通过 doc_root 字段解析
• 对应模块的 eo-doc/dev/<module-name>/spec.md 必须已存在
• 如果 spec 不存在，提示用户先执行 /eo-module-init <module-name>（或独立 /eo-spec）

工作流程

第一步：阅读上下文

1. 阅读 eo-doc/dev/<module-name>/spec.md（需通读全文做完整性审查）——若文件较大、单次 Read 超限，先用 Grep 取章节地图（^#{1,3} ）再按 offset/limit 分段读全，不可因超限而漏读章节
2. 阅读项目级背景文档（如果存在），理解整体背景
3. 执行模板发现（见上方），确定是否启用多层审查维度
4. 扫描 eo-doc/dev/ 下其他 spec 的 frontmatter，检查跨功能一致性
5. 阅读现有代码结构，理解技术现状

第二步：系统审查

按以下维度逐一审查：

维度 1：结构完整性

• 模板中每个章节是否都已填写
• 是否有章节被跳过或用"TODO"、"待补充"等占位符敷衍
• 同目录 spec-history.md 是否已生成（含「模块初始化」初始记录行）

维度 2：需求清晰度

• 每条需求描述是否无歧义
• 是否存在"可能"、"大概"、"应该"、"也许"等模糊词
• 输入/输出的格式、类型、约束是否明确
• 核心行为描述是否足够具体

维度 3：边界与范围

• In Scope / Out of Scope 是否明确且合理
• 是否存在需求范围蔓延的风险
• 已知约束是否完整

维度 4：验收标准质量

• 每条 AC 是否使用 Given-When-Then 格式
• AC 是否可测试、可自动化验证
• 正常路径、边界条件、异常场景是否都有对应的 AC

维度 5：一致性检查

• spec 内部各章节之间是否自相矛盾
• 与已有的其他 spec 是否存在冲突或重叠
• 与项目整体架构和技术约束是否兼容

维度 6：可行性预判

• 需求在技术层面是否可实现
• 是否存在明显的技术风险未被提及
• 非功能需求是否合理

基础设施引用验证原则：

• 新功能引用已有基础设施（配置表、协议定义、枚举、类型等）时，只需验证定义是否存在，不判断业务代码是否已消费。"尚未被业务消费"恰恰是新功能要做的事，不构成可行性问题
• 验证存在性时，搜索定义源头（含自动生成目录），不能仅搜业务逻辑代码就判定"不存在"
• 只有定义源头确实找不到时，才标记为可行性风险

维度 7：多层协作完整性（仅多层项目）

条件维度：仅当 eo-doc/templates/spec-layers.md 存在时启用。 审查依据：以 spec-layers.md 模板定义的结构为标准，逐项检查 spec 的"多层协作需求"章节。

• 结构对照：spec-layers.md 模板要求的每个子章节（交互流向、各层职责划分、需要的数据与通信、一致性检查清单）是否都已填写
• 层覆盖度：project-profile.md 中定义的每个层是否都在职责划分表中出现
• 各层职责是否明确划分，无遗漏
• 交互流向是否覆盖所有层间通信
• 数据与通信需求表是否覆盖所有涉及的层
• 一致性检查清单是否可验证（每条约束有明确的验证方式）
• 是否存在层间职责冲突或重叠
• 禁止事项检查：是否违反模板中的禁止事项（如写了接口签名、消息字段、代码结构）

第三步：撰写审查报告

按照下方固定模板撰写，写入 eo-doc/dev/<module-name>/spec-review.md。

第四步：更新索引

更新 eo-doc/dev/INDEX.md。

固定模板

---
title: <功能名称> Spec 审查报告
spec_name: <spec-name>
tags: [标签1, 标签2]
created: YYYY-MM-DD
updated: YYYY-MM-DD
status: active
summary: >
  一句话概述审查结论。
---

# <功能名称> Spec 审查报告

> 关联 Spec：[spec.md](spec.md)
> 审查日期：YYYY-MM-DD
> Spec 状态：草稿 | 已确认

## 审查总结

一段话概述 spec 整体质量，是否达到可进入 plan 阶段的标准。
给出明确结论：✅ 模块基线通过 / ⚠️ 需小幅修订后通过 / ❌ 需大幅修订

## P0 - 必须修订（阻塞模块基线确认）

### [P0-1] <问题标题>
- **类型**：歧义 / 遗漏 / 矛盾 / 不可行
- **位置**：spec.md 中的章节
- **描述**：问题的具体描述
- **影响**：如果不解决，plan/implement 阶段会产生什么问题
- **建议**：需要补充或修订的方向

## P1 - 建议修订（不阻塞但影响质量）

### [P1-1] <问题标题>
- **类型**：模糊描述 / 边界不清 / AC 不足 / 一致性问题
- **位置**：spec.md 中的章节
- **描述**：问题的具体描述
- **建议**：改进方向

## P2 - 可选优化（锦上添花）

### [P2-1] <问题标题>
- **类型**：措辞优化 / 场景补充 / 格式调整
- **描述**：建议内容

## 结构完整性检查

| 章节 | 状态 | 备注 |
|------|------|------|
| 1.1 功能简述 | ✅ / ❌ / ⚠️ | ... |
| 1.2 所属模块 | ✅ / ❌ / ⚠️ | ... |
| 1.3 关联文档 | ✅ / ❌ / ⚠️ | ... |
| 2.1 目标用户 | ✅ / ❌ / ⚠️ | ... |
| 2.2 用户故事 | ✅ / ❌ / ⚠️ | ... |
| 2.3 使用场景 | ✅ / ❌ / ⚠️ | ... |
| 3.1 输入 | ✅ / ❌ / ⚠️ | ... |
| 3.2 输出 | ✅ / ❌ / ⚠️ | ... |
| 3.3 核心行为描述 | ✅ / ❌ / ⚠️ | ... |
| 3.4 业务规则与约束 | ✅ / ❌ / ⚠️ | ... |
| 4.1 性能要求 | ✅ / ❌ / ⚠️ | ... |
| 4.2 安全要求 | ✅ / ❌ / ⚠️ | ... |
| 4.3 兼容性要求 | ✅ / ❌ / ⚠️ | ... |
| 5.1 In Scope | ✅ / ❌ / ⚠️ | ... |
| 5.2 Out of Scope | ✅ / ❌ / ⚠️ | ... |
| 5.3 已知约束 | ✅ / ❌ / ⚠️ | ... |
| 6. 验收标准 | ✅ / ❌ / ⚠️ | ... |
| 7. 多层协作需求 | ✅ / ❌ / ⚠️ / N/A | 仅多层项目需要 |
| 8. 开放问题 | ✅ / ❌ / ⚠️ | ... |
| spec-history.md | ✅ / ❌ / ⚠️ | 已生成、含初始记录行 |

## 验收标准覆盖分析

| 功能需求 | 对应 AC | 覆盖情况 |
|----------|---------|----------|
| 需求描述 | AC-N | ✅ 已覆盖 / ❌ 缺失 / ⚠️ 不完整 |

关键约束

• 不改 spec：审查只产出报告，不直接修改 spec.md
• 客观依据：基于模板标准和项目上下文审查，不做主观偏好评判
• P0 必须精准：只有真正阻塞模块基线建立、会导致后续 change 反复澄清的问题才标为 P0
• 可操作：每个问题的建议必须具体到用户能直接行动
• 区分"存在"与"消费"：新功能引用的已有基础设施，验证其定义是否存在即可。"当前未被业务消费"不构成问题
• 搜索含定义源头：验证基础设施是否存在时，必须搜索定义源头（含自动生成目录），不能仅搜业务代码