| name | review1-raise |
| description | [Reviewer] Analyze local git diff (with optional user-supplied extra scope) and produce a structured review document with numbered findings (R1, R2...). Part of a 5-stage adversarial ping-pong review: raise(R) → reply(D) → confirm(R) → execute(D) → accept(R). |
review1-raise — 产出评审报告
分析代码改动，生成结构化 review 文档，为后续 review2-reply / review3-confirm / review4-execute / review5-accept 提供输入。
角色
Reviewer Agent — 本阶段由 Reviewer 执行，是五阶段对抗性 ping-pong 流程的第一棒：
raise(R) → reply(D) → confirm(R) → execute(D) → accept(R)
对抗假设：代码中存在作者未察觉的缺陷、设计短视或一致性问题。积极挖掘，不因代码"能跑"就放水。严重程度要客观标定——风格偏好可以提，但不得标为"严重"。预设 Defender 在 review2-reply 中会反驳弱势 Review，因此每条 Review 必须有充分依据，禁止模糊措辞。
分析范围
- 默认：
git diff HEAD（已暂存 + 未暂存）
- 补充：用户可在调用时追加范围，如特定路径、提交区间、额外文件等
- 最终执行：
git diff HEAD [补充范围] 及 git diff --stat HEAD [补充范围]
- 审阅 OpenSpec 文档时：OpenSpec 文件位于
openspec/changes/ 目录，通常被 .gitignore 排除，git diff 无法追踪。此时跳过 diff 收集，直接读取 openspec/changes/ 下的目标目录/文件作为评审对象。评审产物仍走 .temp/review-*.md 流程不变。
步骤
-
检查历史 review 记录（由主 Agent 执行）：
- 执行
ls -t .temp/review-*.md 获取历史文档列表
- 逐个用
head -n 15 .temp/review-xxx.md 读文档开头，查看"评审范围"中涉及的文件路径
- 若和当前
git diff --stat HEAD 涉及的文件有重叠，视为相关文档；用 read 读取完整内容
- 从相关文档中提取精简信息：各 Rn 的共识状态（
已共识·实施 / 已共识·延后 / 已共识·否决 / 已共识·存档(旧) / 验收退回 等）及核心问题描述
- 这些精简信息作为约束提供给子 Agent，避免子 Agent 上下文被大量历史内容占满
-
收集 diff（默认 + 用户补充）
-
若无改动，直接退出
-
判定评审对象类型：非代码文档（如 openspec/changes/ 下的设计文档）走设计文档评审分支，跳过步骤 5（档位判定），直接进入步骤 6。
- 识别方式：用户指定路径在
openspec/changes/ 下，或 diff 为空但用户明确提供了文档目标。不确定时凭文件内容自行判断（设计文档 vs 代码改动）
- 设计文档评审不分档，固定使用 2 个 Agent（见步骤 6 的 Design 行）
-
判定评审档位（代码改动专用，设计文档跳过）：基于 git diff HEAD --numstat 统计改动规模（排除 tests/、docs/ 目录及 *.md 文件）：
| 档位 | 条件 | Agent 数 |
|---|
| light | < 100 行 且 < 5 非 test/doc 文件 | 1 |
| normal | 兜底（不满足 light 也不满足 deep） | 2 |
| deep | ≥ 1000 行 或 ≥ 8 非 test/doc 文件 | 3 |
统计命令参考：
git diff HEAD --numstat | awk '
$3 !~ /^(tests\/|docs\/)/ && $3 !~ /\.md$/ { files++; added+=$1; deleted+=$2 }
END { printf "files=%d, added=%d, deleted=%d\n", files, added, deleted }'
-
根据档位/类型，同时启动对应数量的子 Agent 评审——不等其中一个完成再启动另一个；代码评审时让 Agent 自行读取代码与 diff，设计文档评审时让 Agent 自行读取文档，不要把评审对象文本直接传给 Agent；任一 Agent 启动失败时，不得单独继续，向用户确认后再决定下一步：
子 Agent 通用约束（所有 Agent 适用）：
- 子 Agent 只负责分析并输出评审意见，不需要运行 pytest 测试，测试由主 Agent 在后续步骤统一执行
- 若子 Agent 运行超过 15 分钟，说明可能陷入无限循环，主 Agent 应终止该子 Agent 并重新启动调查
- 如有历史 review 精简信息，子 Agent 应先阅读，避免重复提出之前已闭环（已共识·存档 或 已共识·实施）的同类问题
子 Agent 启动方式：使用 Agent 工具，subagent_type 固定为 general-purpose，description 字段写明 Agent 名称与职责，prompt 字段开头注明 ## 审查任务 和要审查的目标范围，然后 ## 审查要求 引用对应的 prompt 文件内容。prompt 文件路径（相对于本 SKILL.md 所在目录）：
Design（2 Agent，设计文档）
| Agent | prompt 文件 | 粒度 |
|---|
| A — 需求与方案 | prompt_design_a.md | 问题定义、替代思路、过度与不足 |
| B — 落地与影响 | prompt_design_b.md | 技术可行性、架构一致性、遗漏点 |
A 聚焦"想得对吗？还有更好的吗？"，B 聚焦"能做吗？搭吗？还有什么没想到？"。各 Agent 输出分为「问题」和「提议」两部分。
Light（1 Agent）
| Agent | prompt 文件 |
|---|
| 综合审查 | prompt_light.md |
覆盖微观正确性、中观设计、宏观彻底性三个维度，深度精简。
Normal（2 Agent）
| Agent | prompt 文件 | 粒度 |
|---|
| A — 实现质量 | prompt_normal_a.md | 行/函数级 |
| B — 设计质量 | prompt_normal_b.md | 模块/文件级 |
Deep（3 Agent）
| Agent | prompt 文件 | 粒度 |
|---|
| A — 微观正确性 | prompt_deep_a.md | 行/函数级 |
| B — 中观设计 | prompt_deep_b.md | 模块/文件级 |
| C — 宏观审视 | prompt_deep_c.md | 项目/架构级 |
ABC 三者视角互不重叠：A 只看"这行代码对吗"，B 只看"这几个文件搭得好吗"，C 只看"整体方向对吗 / 改全了吗"。
-
收集所有子 Agent 的完整输出，将其作为参考线索而非最终结论——最终报告由本 Agent 独立负责，不得直接照搬任一 Agent 的原文：
- 逐条回到代码/文档重新核查，形成独立判断后再写入报告
- 多 Agent 结论互相矛盾时，重新审查后统一意见，不得将分歧直接暴露在报告中
- 仅一个 Agent 提出的条目，独立核查后决定是否成立，不因"只有一个提到"而自动降级或升级
- 类似问题合并后重新描述，不得压缩成仅含标题的清单，修改建议必须具体可执行
- 严重问题的测试覆盖：对严重程度为"严重"的问题，若所有子 Agent 的修改建议均未提及回归测试，Reviewer 应独立评估是否需要补充测试建议
- 对照历史 review：若某条问题在之前的 review 中已被标记为
已共识·否决 或旧版 已共识·存档，本轮不再重复提出；若之前标记为 已共识·实施 但当前代码仍未修复，可再次提出并注明"历史遗留"；若之前标记为 已共识·延后，本轮不重复提出，但可在新问题中引用 backlog ID
-
用户体验改动门禁：检查所有问题中是否存在影响功能设计或用户体验的建议（即不是代码 bug 修复或内部实现优化的条目）。若有，逐一和用户确认，用户明确同意保留的建议方可写入文档，未确认的直接剔除
-
整理问题列表，按 R1, R2... 编号
-
一次性写入：调用脚本创建文档，通过 heredoc 直接传入完整内容（仅允许这一次写入操作）：
python .claude/skills/review1-raise/review_record.py create <主题slug> <<'EOF'
...
EOF
脚本自动生成时间戳，输出完整文件路径（如 .temp/review-260420-1530-<主题>.md），后续步骤使用此路径。
文档格式
评审代码改动时：
## 本地改动与分支 Review
**阶段状态**
- [x] 1. 评审发起 (review1-raise)
- [ ] 2. 作者回复 (review2-reply)
- [ ] 3. 审阅者确认 (review3-confirm)
- [ ] 4. 实施 (review4-execute)
- [ ] 5. 验收 (review5-accept)
**评审范围**
- 默认范围: git diff HEAD
- 补充范围: (若有)
- 当前分支: <branch>
---
### R1 — <标题>
**Review**
- 严重程度: 严重/警告/建议
- 问题描述: ...
- 修改建议: ...
### R2 — <标题>
**Review**
...
评审设计文档时，标题改为 ## 设计文档评审 — <文档名>，评审范围写明文档路径。
Worktree 路径规范
当评审对象是 worktree 中的未提交改动时，所有操作必须在目标 worktree 中执行，不可写入 dev 目录：
- 历史 review 检查：步骤 1 的
ls -t .temp/review-*.md 必须在目标 worktree 根目录下执行，读取目标 worktree 中的历史 review 记录。
- diff 收集：
git diff HEAD 必须在目标 worktree 目录下执行，确保 diff 来自目标 worktree 的未提交改动。
- 评审报告生成：步骤 10 的
review_record.py create 必须在目标 worktree 目录下执行，生成的 .temp/review-*.md 位于目标 worktree 根目录，随 worktree 一起清理/提交。
- 脚本路径：
review_record.py 等脚本的调用必须在目标 worktree 目录下执行，确保相对路径解析正确。
输出
向用户报告生成的文件路径（位于 .temp/），并提示下一步：
review2-reply <文件名>
