| 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 即可）。
核心原则
- 对照模板审查：严格依据 spec 模板检查每个章节的完整性与质量
- 发现歧义：识别所有可能导致 plan/implement 阶段产生分歧的模糊描述
- 不改 spec：审查只产出报告，修订工作由用户决定后通过
/eo-spec 执行
- 固定产出：输出到
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）
工作流程
第一步：阅读上下文
- 阅读
eo-doc/dev/<module-name>/spec.md（需通读全文做完整性审查）——若文件较大、单次 Read 超限，先用 Grep 取章节地图（^#{1,3} ）再按 offset/limit 分段读全，不可因超限而漏读章节
- 阅读项目级背景文档（如果存在），理解整体背景
- 执行模板发现（见上方），确定是否启用多层审查维度
- 扫描
eo-doc/dev/ 下其他 spec 的 frontmatter，检查跨功能一致性
- 阅读现有代码结构，理解技术现状
第二步：系统审查
按以下维度逐一审查：
维度 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
- 可操作：每个问题的建议必须具体到用户能直接行动
- 区分"存在"与"消费"：新功能引用的已有基础设施，验证其定义是否存在即可。"当前未被业务消费"不构成问题
- 搜索含定义源头：验证基础设施是否存在时，必须搜索定义源头（含自动生成目录），不能仅搜业务代码
