| name | code-review |
| description | Review code changes for correctness, regressions, edge cases, style issues, and unnecessary churn. Use when checking diffs, reviewing pull-request-like changes, or doing independent quality review. Triggers on "review this", "check my changes", "code review", "代码审查". |
code-review
独立的代码审查技能。读 diff（或一组改动文件），按结构化清单评估，输出按严重度分组的发现。不修改任何代码——只产出报告供用户决策。
触发条件
- 用户说"帮我 review"、"检查改动"、"code review"、"代码审查"
- 用户分享 PR / 一段 diff
- workflow
/review-changes 或 /verify-result 路由到本技能
safe-refactor 完成阶段性改动后自动调用（互补关系：refactor 做改，review 验改）
前置条件
- 工作区里有未提交改动 或 给定明确的 commit range / file list
- 如果是 PR review，先
gh pr diff 或 git diff 拿到改动集
执行步骤
Step 1: 确定 review 范围
- 如果用户没指定，默认对当前未提交改动 (
git status + git diff) 做 review
- 如果指定了 commit / branch / PR，明确范围并向用户复述确认
- 大改动（>500 行 diff）先拆分：按文件 / 按职责分批
Step 2: 加载上下文
- 读完整的被改动文件（不只是 diff 中显示的几行）——
Read 工具读整文件，至少看清楚函数边界
- 读引用方：用
Grep 找谁调用了被改函数 / 谁导入了被改模块
- 读测试：被改代码是否有测试？测试是否被同步更新？
Step 3: 按 6 维清单审查
按以下顺序检查，每条记录具体 file:line 引用：
- Correctness（正确性）: 代码是否做了它声称的事？看 docstring / commit message 是否与实际逻辑匹配
- Regressions（回归风险）: 已有功能是否可能被破坏？特别看：
- 被改函数的所有调用方是否还能用
- 公开 API（schema、CLI args、env vars）是否保持向后兼容
- 共享状态 / 全局变量 / 单例
- Edge Cases（边界）: 异常输入、空集合、None、并发、I/O 失败是否处理
- Interface Risk（接口风险）: public 或 internal contract 是否被无意改动（rename、参数顺序、返回类型）
- Test Coverage（测试覆盖）: 改动是否有对应测试？新 branch / new error path 是否被测
- Churn（多余改动）: 有没有可以简化 / 删除的部分？有没有偏题改动应该单独 commit
Step 4: 生成报告
输出格式：
# Code Review: {scope}
## Critical (must fix before merge)
- [file:line] {issue}: {why it's critical}
## Important (should fix)
- [file:line] {issue}: {recommended fix}
## Nit (style / minor)
- [file:line] {issue}
## Suggested next checks
- {what to verify next, e.g. "run integration tests on stage X"}
按严重度排序。每条必须带 file:line 锚点（markdown link 格式 [file.py:42](file.py#L42)），不写笼统"some code smells"。
输出契约
返回 markdown 报告（向用户终端打印）。不落盘到 artifacts/——code-review 是即时反馈，不进入 evidence_graph。如果用户后续要 fix，由用户决定是否调 safe-refactor / systematic-debugging。
失败处理
- diff 过大（>1000 行）→ 先警告用户，建议拆分 PR 后再 review
- 无法访问被引用的外部依赖（例如改动调了未安装的库）→ 报告 "[BLOCKED] unable to verify X because Y"，不编造判断
- 改动跨多个 unrelated 子系统 → 拆分报告（按子系统分节）
与其他技能的关系
- systematic-debugging: review 找到 bug → debug 定位 root cause → fix
- safe-refactor: refactor 做改动 → review 验证保留语义
- test-author: review 标出"缺测试" → test-author 补
- verification-runner: review 标出"应该跑 X 测试" → verification 实际执行
遵守规则
.agents/rules/repo-architecture.md: 不允许 review 时建议跨模块违规修改.agents/rules/evidence-discipline.md: review 报告中的 claim 必须有 file:line 证据
Severity-blocking review（强制 severity 协议）
"建议性" review 是噪声。NeXus 的 review 必须把每条评论钉死在 4 级 severity 上，让作者 一眼看出"必须改 vs 可选改"。
没标 severity 的评论视为 NIT，但不允许这样写——所有评论都必须显式标级。
四级 severity 定义
| Severity | 含义 | Merge 影响 |
|---|
| CRITICAL | 会导致正确性 / 安全 / 数据丢失 / 公开契约违反 | 阻断 merge，必须修后重新 review |
| IMPORTANT | 不立刻坏，但显著放大未来 bug 风险（缺测试覆盖、错误处理缺失、回归风险、文档与代码不一致） | 必须 address——修、或给出 reviewer 同意的 defer 理由 |
| NIT | 风格 / 命名 / 局部可读性 / 微优化 | 建议性，作者可拒绝且无需解释 |
| PRAISE | 优秀实践 / 正确的设计判断 | 正向反馈，鼓励同类做法被复用 |
每级的强制结构
每条 review comment 必须在 file:line 之后立刻打 [CRITICAL] / [IMPORTANT] / [NIT] / [PRAISE] 标签，并满足该级的"必填字段"：
- CRITICAL 必填两项：
- 为什么 block：具体说出"会引发什么样的错误"——不能写"this looks wrong"，要写"input X 会触发 ZeroDivisionError，调用方未捕获"
- 怎么修：给出可执行的修法（patch 思路 / 替换代码 / 调用替代 API），让作者无需再追问
- IMPORTANT 必填一项：
- 修改后预期结果：明确"改完之后我期望看到 X"（例：新增 test case 覆盖 None 分支、错误码统一为 ValueError、log 改为 warning 级）
- NIT 必填：
- 只需指出位置 + 建议，不需要解释影响（因为本来就可拒绝）
- PRAISE 必填：
- 指出做对了什么 + 为什么这是好实践（让读者能复用此判断，不是空洞的 "nice"）
不允许的 ambiguous 评论
下列写法在 NeXus review 报告里禁止出现——它们既不阻断也不可执行，纯属噪声：
- ❌ "could be better"、"maybe consider"、"feels off"——没有 severity，也没有 actionable 建议
- ❌ "this is a bit complex"——没说复杂在哪、对应哪一级、要怎么改
- ❌ "I'd probably do it differently"——表达偏好不是 review
- ❌ 只给 severity 不给"为什么 block / 修改后预期"（CRITICAL/IMPORTANT 的必填字段缺失）
- ❌ 标了 CRITICAL 但实际只是风格问题 —— 滥用 CRITICAL 等同噪声，会被作者降权所有 critical 标签
若一条评论确实拿不准 severity，默认降为 NIT 并加一句"为什么没标 IMPORTANT 的判断依据"——宁可漏报也不滥报。
报告输出补强
报告第一行必须给出 severity 直方图：CRITICAL=N, IMPORTANT=N, NIT=N, PRAISE=N，让作者 / merger 一眼定位 review 结论：
CRITICAL ≥ 1 → 不允许 merge，必须修CRITICAL = 0, IMPORTANT ≥ 1 → 可 merge 但需作者明确处理意见（修 / defer with reason）CRITICAL = 0, IMPORTANT = 0 → 通过，NIT 可选采纳
