code-review

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 引用：

1. Correctness（正确性）: 代码是否做了它声称的事？看 docstring / commit message 是否与实际逻辑匹配
2. Regressions（回归风险）: 已有功能是否可能被破坏？特别看：
   • 被改函数的所有调用方是否还能用
   • 公开 API（schema、CLI args、env vars）是否保持向后兼容
   • 共享状态 / 全局变量 / 单例
3. Edge Cases（边界）: 异常输入、空集合、None、并发、I/O 失败是否处理
4. Interface Risk（接口风险）: public 或 internal contract 是否被无意改动（rename、参数顺序、返回类型）
5. Test Coverage（测试覆盖）: 改动是否有对应测试？新 branch / new error path 是否被测
6. 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 必填两项：
  1. 为什么 block：具体说出"会引发什么样的错误"——不能写"this looks wrong"，要写"input X 会触发 ZeroDivisionError，调用方未捕获"
  2. 怎么修：给出可执行的修法（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 可选采纳