deepreview

name	deepreview
description	用于对当前未合并 workspace changes、指定 GitHub Pull Request 或仓库全部代码做严格深度 code review；支持 `$deepreview`、`$deepreview 当前改动`、`$deepreview --base main`、`$deepreview --base ref`、`$deepreview --pr 123` 和 `$deepreview --all`；在 docs/reviews 下写完整 review artifact，优先 correctness、stability、maintainability findings，包含 adversarial failure pass、项目指令检查、过度耦合检查、semantic ownership drift 检查，并最终只简要报告结论和输出路径。

Deepreview

Deepreview 执行严格、基于证据的 code review。它有三种 mode：

• Current Changes Mode：review 当前 workspace 和 branch 相对 main 或指定 base ref 的 changes。
• PR Review Mode：review 指定 Pull Request 相对其 base branch 的完整 diff。
• All Repository Mode：review 仓库中的全部代码。

当用户要求 strict review、deep review、current unmerged changes review、PR review 或 full repository review 时，使用这个 skill。

Invocation Handling

直接映射这些短指令：

$deepreview
$deepreview 当前改动
$deepreview current changes
$deepreview --base main
$deepreview --base <ref>

使用 Current Changes Mode。裸 $deepreview 等价于 $deepreview --base main。如果提供了 --base <ref>， 就 review 当前 workspace 和 branch 相对该 base ref 的 changes，而不是默认 main。

$deepreview PR 123
$deepreview pr 123
$deepreview --pr 123

对 PR number 123 使用 PR Review Mode。

$deepreview --all
$deepreview all
$deepreview full
$deepreview repo
$deepreview 全部代码
$deepreview 整个仓库

使用 All Repository Mode。

如果同时提供 --all 和 --pr <number>，必须询问用户是要 review 整个仓库还是指定 PR，不要自行选择。 如果同时提供 --all 和 --base <ref>，使用 All Repository Mode，并把 --base 仅作为可选参照基线记录到 scope。 如果同时提供 --pr <number> 和 --base <ref>，使用 PR Review Mode，并把 --base 仅作为需要核对 PR base branch 的显式期望。如果用户要求 PR review 但没有给 PR number，先询问 PR number。若请求无法判断是 current changes、PR mode 还是 All Repository Mode，只问一个简短澄清问题。

Output Contract

始终把完整 review 结果写入 docs/reviews/ 下的 markdown 文件。目录不存在时创建。

写 review artifact 前，必须从本机系统时钟生成 timestamp。不要推断、手写或编造 timestamp。不要使用 001 这类计数器。

运行或执行等价操作：

mkdir -p docs/reviews
ts="$(date +%Y%m%d-%H%M%S)"

Current Changes Mode 使用生成的 timestamp：

docs/reviews/code-review-${ts}.md

PR Review Mode 使用生成的 timestamp：

docs/reviews/pr-<pr_number>-review-${ts}.md

All Repository Mode 使用生成的 timestamp：

docs/reviews/repo-review-${ts}.md

写入前，确认路径匹配以下格式之一：

docs/reviews/code-review-[0-9]{8}-[0-9]{6}.md
docs/reviews/pr-<pr_number>-review-[0-9]{8}-[0-9]{6}.md
docs/reviews/repo-review-[0-9]{8}-[0-9]{6}.md

最终回复用户时，只简要说明 review conclusion 和 output file path。

Review Method

Current Changes Mode：

1. 先理解 change intent：阅读相关 notes、diff、commit scope、关键实现和 tests，判断改动声称要解决什么问题。

2. 再对齐 contracts 和 sources of truth：检查 AGENTS.md / CLAUDE.md、相关 README 或 design docs、 public interfaces、schemas、state machines、configuration、storage 或 external protocols。

3. 继续追踪 implementation paths：跟随关键 call chains、data flow、error paths 和 risk points，例如 concurrency、idempotency、retry、cancellation、recovery。不要只 review 表层 diff。

4. 以真实入口为起点检查完整主链路。必须沿真实代码路径逐行走读，禁止猜测；root cause 必须来自同一条逻辑或数据路径上的直接证据。

5. 对关键 public functions，以及分支复杂、状态更新复杂或 I/O 边界明显的 private helpers，按这个顺序展开：

   入参 -> 条件判断 -> 下游调用 -> 返回值 / raise -> 副作用
   

6. 检查所有关键 if / elif / match / dispatch / router 是否由真正决定该分支的事实驱动，而不是由间接信号、 historical flag、cached marker 或碰巧相关字段驱动。

7. 对关键参数、配置、override 和 request options 展开生效链：来源 -> 覆盖关系 -> 最终消费点 -> 非法值处理。 如果值只进入中间对象但最终未被执行层读取，或在链路中被重新默认化、覆盖、丢失、静默忽略，即报告。

8. 对返回值、持久化状态、外部可见状态、event/log/trace 做一致性检查。任何“返回成功但状态半提交”“外部显示完成但系统仍可恢复或运行中” 或“错误被默认成功值掩盖”的情况，都必须沿同一执行事实追踪。

9. 执行 adversarial failure pass 和 semantic ownership drift pass：默认怀疑，寻找最强的、基于证据的理由说明该 change 还不该 ship；特别检查是否由无所有权的下游通过 fallback、特例、重复计算、loose parsing、兼容 shim 或测试固化来补齐上游 contract。如果只覆盖 happy path，把它视为真实弱点。

10. 最后 review tests and risk：判断 tests 是否覆盖真实行为、failure paths、boundary conditions 和 regression surfaces，识别重要剩余未覆盖风险。

PR Review Mode 使用相同方法，但从 PR title/description 开始，并在最后的 tests and risk review 中包含 CI/check information。

All Repository Mode 使用相同方法，但没有单一 diff intent。reviewer 必须先建立 repository map：读取项目指令、 目录结构、README/design docs、public entry points、package/module boundaries、tests、schemas、storage、 external protocol adapters 和关键 runtime paths。然后按风险优先级选择真实入口与关键链路逐条走读。不能只做 文件列表式扫描，也不能把没有覆盖的区域写成已 review。

Adversarial Attack Surface

adversarial failure pass 中，优先寻找高成本、危险、用户可见或难以发现的失败：

• auth、permissions、tenant isolation、trust boundaries、privilege escalation；
• data loss、corruption、duplication、stale facts、irreversible state changes；
• rollback safety、retries、partial failure、re-entrancy、idempotency gaps；
• race conditions、ordering assumptions、stale state、ownership conflicts、late writes；
• empty-state、null、timeout、cancellation、degraded dependency、unavailable dependency behavior；
• missing required parameters、type errors、invalid enum/string values、empty content/message/prompt、 out-of-range numbers、negative numbers、oversized inputs；
• duplicate requests、conflicting parameters、already-terminal state being advanced again；
• version skew、schema drift、migration hazards、compatibility regressions、mixed old/new state；
• observability gaps，导致失败被隐藏、audit 不可能或 recovery 更困难；
• externally visible inconsistency between return values, persisted state, delivery state, events, logs, traces, and read models；
• external protocol/API boundary issues：payload shape mismatch、correlation id mismatch、one-to-one response mapping errors、stream/page/chunk assembly bugs、finish/error reason conflation、malformed response handling gaps、protocol-layer product semantics leakage；
• overcoupling issues：本应独立演进的层、模块、状态机、数据模型、工具、测试或 rollout 被绑成一个必须同步修改的整体； 本应基于 Protocol / interface 的结构被设计成基于具体实现，导致替换实现、隔离测试或跨层复用时需要穿透修改；
• semantic ownership drift：事实、状态、错误原因、格式、业务裁决、协议语义或展示语义由错误 owner 产生、解释、 持久化或修正，导致下游用 fallback、特例、重复计算、loose parsing、兼容 shim 或测试固化补齐 contract；
• statically provable performance problems：loop-internal expensive recomputation or I/O、repeated JSON/regex parsing、list membership where set is required、unnecessary full loading、blocking I/O in async code、N+1 I/O patterns；
• test gaps，只证明 happy path。

Large Scope Parallel Review

当 review scope 很大、跨多个模块，或同时涉及 state machine、storage、concurrency、contract、public API、migration 等多个高风险面时，可以使用 subagents 做并行专项 review，以提高覆盖和深挖质量。

使用 subagents 时必须遵守：

• 主 reviewer 仍对最终 review artifact 负责；
• 每个 subagent 必须有明确 scope，例如文件集合、真实入口、调用链、状态机、contract boundary、测试面或风险面；
• 不要让 subagent 泛泛 review 整个 diff；
• 每个 subagent 必须沿真实代码路径走读，只输出 evidence-based findings、open questions、residual risks 和未覆盖区域；
• 主 reviewer 必须整合、去重、复核证据链、裁决 severity，并丢弃无法被同一逻辑 / 数据路径直接证据支撑的 finding；
• 主 reviewer 必须检查不同 subagent 结论之间是否冲突，必要时回到代码路径复核；
• 最终 artifact 必须记录哪些区域由 subagent 覆盖，哪些区域仍未覆盖。

subagent 适合做并行深挖，不适合替代主 reviewer 的最终判断。不要把多个 subagent 输出直接拼接成 review 结论。

Review Requirements

• 使用 code review mode。优先找真正影响 correctness、stability 或 maintainability 的 defects。
• 默认怀疑。目标不是证明改动看起来合理，而是找出最强证据说明它可能不适合 merge。
• 不因为 good intent、partial fixes 或可能的 follow-up work 给改动加分。
• 先检查改动是否违反 repository instructions，例如 AGENTS.md / CLAUDE.md。
• 重点关注 intent 与 implementation 的 semantic mismatch、logic errors、boundary conditions、regression risk、 type issues、exception handling、resource release、concurrency safety、idempotency、data consistency、 observability、missing tests，以及与 existing architecture constraints 的不一致。
• findings 必须基于直接证据：code、diff、docs、test gaps、CI information 或可复现推理。不确定的问题放到 Open Questions，不要当成确定 defect。
• root cause 必须与触发输入、实际分支、状态写入、返回值或副作用处在同一条逻辑 / 数据路径上。禁止用间接迹象、 相邻代码味道或“看起来相关”的字段替代根因证据。
• 审查 architecture boundary：下层接口不得泄漏上层治理、业务受理或展示状态；禁止反向 import；警惕跨层穿透调用。
• 审查 overcoupling / 过度耦合：检查代码是否把本应独立演进的层、模块、状态机、数据模型、工具、测试或 rollout 步骤绑成一个必须同步修改的整体；是否出现跨层穿透、双向依赖、共享可变状态、过宽公共契约、为了局部行为修改过多 ownership boundary，或 future work 被当前实现结构锁死。
• 审查 Protocol / interface 边界：本应依赖稳定 Protocol、interface、ABC 或公共契约的调用方，不应直接依赖具体实现类、 concrete storage/runner/executor/client、内部 builder 或测试替身。若具体实现依赖导致替换实现、隔离测试、分层复用或 contract evolution 需要跨模块联动，即作为 maintainability / architecture finding 报告。
• 审查 public API exposure：检查 public modules、package exports、README/examples 或便利 import 是否把内部实现对象呈现为推荐接口， 诱导上层或调用方绕过稳定契约。若暴露面会造成 contract drift 或错误依赖内部对象，即报告。
• 审查 contract ownership：如果语义真源只在一层，契约归属该语义真源所在层；如果多个层都需要独立实现、产生、 解释或持久化同一语义，且它描述的是层间协作协议而不是某一层的调用参数，则契约应落在公共契约。
• 审查 semantic ownership drift / minimum-design trap：事实、状态、错误原因、格式、业务裁决、协议语义或展示语义必须由正确 owner 产生、解释、持久化并对外承诺。只有存在直接证据时才报告，例如当前 change 正在扩大该模式，或已有 fallback、 特例、hasattr / getattr、loose parsing、重复计算、二次格式化、兼容 shim、测试固化、隐性字符串协议、 多真源状态、下游修正上游语义。不要把“未来也许更通用”或个人抽象偏好当 finding。报告此类 finding 时，必须说明： 正确 owner 是谁、语义漂移到了哪里、哪条直接证据证明风险已存在、如何把 contract 收束回 owner 或显式化。
• 审查 branch ordering：宽条件是否抢先命中导致更具体分支不可达；条件是否重叠但无明确优先级；是否缺少默认分支导致异常输入悄悄落空； dispatch/router/builder/handler 是否同时承担参数转换、分支选择和结果合并，导致分支逻辑被错误复用或漏判。
• 审查 structural clarity / spaghetti-code risk：控制流是否清晰，职责是否收敛，函数或类是否承担过多分支，状态是否被多处隐式修改； 是否出现跨多层长链路 glue code、布尔标记驱动的隐式流程、深层嵌套、分支交叉复用、隐藏副作用、god function/object/dataclass 或难以局部推理的实现。即使当前行为正确，只要结构让后续修改容易引入回归，也应作为 maintainability / architecture finding 报告。
• 审查 parameter effectiveness：关键参数必须能追踪来源、覆盖优先级、最终消费点和失效处理。若传入值与最终生效值之间没有直接数据链， 或 caller 预期与实现优先级不一致，即报告。
• 凡是存在“真源状态 + 触发条件 + 状态写入 + 对外事件 / 副作用 + 后续收敛”的闭环，都按 state machine 审查。 每个关键 state machine 至少展开正常主路径、失败路径、取消 / 超时 / interrupt 路径、resume / retry / redelivery / continuation 恢复路径，以及竞争写入、孤儿状态、cleanup 或外部终态收敛等并发 / 调和路径。
• 审查 state machine ownership：明确 state source of truth、谁有权推进状态、哪些状态是 terminal/absorbing、重复操作是否应幂等吸收。 若同一事实存在多个可写真源、推进权分散、终态可回退/覆盖，或异常路径和正常路径使用不同转换规则，即报告。
• 审查 external protocol/API boundaries：协议适配层必须区分协议事实和产品语义；payload shape、关联 id、顺序、一一对应关系、 stream/page/chunk 拼接、finish/error reason 和畸形返回必须有明确处理。不要把业务判断塞进协议层，也不要把协议错误当正常成功。
• 主动检查非预期输入：缺失必填参数、类型错误、非法枚举 / 非法字符串、空内容 / 空消息 / 空 prompt、越界数值、 负数、超长输入，以及重复请求、冲突参数、已终态再次推进。
• 只报告可通过静态代码阅读证明的性能问题，例如循环内重复重计算或 I/O、重复 JSON/regex parsing、应使用 set 却用 list 成员查找、 不必要全量加载、async 路径中的同步阻塞 I/O、N+1 I/O。不要提出猜测性优化建议。
• 不只问 tests 是否存在。要判断 tests 是否真正证明关键行为，是否遗漏 failure paths、boundary conditions 或 regression scenarios，assertions 是否为了适配实现而被削弱。
• 每个 finding 必须回答：what can go wrong、为什么该 code path 脆弱、可能影响是什么、什么具体修改能降低风险。
• 宁可一个强 finding，也不要多个弱 finding。不要用 style feedback、naming feedback、低价值 cleanup 或无证据猜测稀释严重问题。
• 如果没有明确实质问题，写 未发现实质性问题。
• findings 放在最前面，并按 severity 排序。每个 finding 必须使用下方固定 finding format。
• findings 之后包含 Open Questions 和 Residual Risk；为空时写 无。
• 不要以 summary 开头。不要泛泛表扬。不要把风格偏好当作主要 findings。

最终输出前，检查每个 finding 是否：

• 绑定到具体 code location 或 explicit behavior；
• 在真实 failure scenario 下可信；
• evidence-based，而不是 speculative；
• 对修复问题的工程师可执行。

固定 finding format 用于强制 reviewer 识别 entry point、triggering input、actual branch、expected behavior、 actual behavior、direct evidence、impact、fix direction、fix risk 和 severity。

Current Changes Mode

用户要求 review current code changes、current branch changes 或 unmerged changes 时使用。

review scope：

• 相对 selected base ref 的所有 workspace changes，默认 base 是 main；
• staged changes；
• unstaged changes；
• 当前 branch 上尚未 merge 到 selected base ref 的 committed changes。

判断前，检查相关 git diff、changed files、关键 implementation files、tests 和 project instructions。优先直接证据， 不要用间接迹象代替根因判断。

推荐命令：

git branch --show-current
git status --short
git diff <base>...HEAD
git diff
git diff --cached

除非用户提供 --base <ref> 或 repository facts 表明 base 应不同，否则使用 main 作为 <base>。review artifact 中必须记录 selected base。

PR Review Mode

用户要求 review PR 或提供 PR number 时使用。

review 前收集 PR facts：

• repository；
• PR number；
• title；
• author；
• head branch；
• base branch；
• URL。

review scope：

• PR 相对 base branch 的完整 diff；
• key implementation files；
• related tests；
• CI/check information，若相关。

推荐命令：

gh repo view --json nameWithOwner --jq '.nameWithOwner'
gh pr view <pr_number> --json title,url,author,headRefName,baseRefName
gh pr diff <pr_number>
gh pr checks <pr_number>

如果无法读取 GitHub metadata，清楚说明 blocker，不要编造 PR facts。

All Repository Mode

用户要求 review 全部代码、整个仓库、full repository review，或使用 $deepreview --all 时使用。

review scope：

• 仓库中所有生产代码；
• 与生产代码行为相关的 tests；
• public entry points、package/module exports、README/design docs；
• schemas、storage/migration、configuration、external protocol adapters；
• CI/check 配置，若它影响 review 结论。

先建立 repository map，再按风险优先级划分 review slices。至少记录：

• repository root；
• branch；
• review date/time；
• included directories；
• excluded directories and reason，例如 generated/vendor/build/cache；
• high-risk entry points and subsystems；
• parallel review coverage，若使用 subagents；
• not-covered areas，若因为范围过大无法完整走读。

推荐命令：

git branch --show-current
git status --short
rg --files
find . -maxdepth 3 -type f \( -name 'README*' -o -name 'AGENTS.md' -o -name 'CLAUDE.md' \)

All Repository Mode 默认应使用 Large Scope Parallel Review。每个 subagent 或 review slice 必须有明确范围： 目录、入口、调用链、状态机、contract boundary、storage/schema、external protocol 或测试面。最终 artifact 必须清楚区分 covered、partially-covered 和 not-covered areas。

不要把全仓 review 做成纯 lint、命名或风格 review。仍然只报告有直接证据、真实执行路径或明确架构风险支撑的 material findings。

Review Artifact Format

使用这个结构：

# Code Review

## Scope

- Mode: current changes | PR | all repository
- Branch or PR:
- Base:
- Output file:
- Included scope:
- Excluded scope:
- Parallel review coverage: 无，或列出 subagent 覆盖的文件/链路/风险面与未覆盖区域

## Findings

### 编号-未修复-[严重程度（低/中/高/严重）]-finding简述
- **入口/函数**: 问题发生在什么执行入口或什么函数
- **文件(行号)**: 具体位置
- **输入场景**: 什么输入会触发问题
- **实际分支**: 代码实际走到了哪个分支
- **预期行为**: 按当前系统设计应该如何处理
- **实际行为**: 现在返回了什么、写入了什么状态、或漏做了什么
- **直接证据**: 具体判断条件、参数传递路径、返回值或状态更新位置（行号）
- **影响**: 错误 answer / 错误状态 / 静默失效 / 不可恢复 / 仅局部行为错误
- **建议改法和验证点**:
- **修复风险（低/中/高）**:
- **严重程度（低/中/高/严重）**:

## Open Questions

- 无，或列出阻碍 confident judgment 的问题。

## Residual Risk

- 记录 test gaps、CI gaps 或未检查区域。

如果没有 findings，保留简短的 ## Findings，写 未发现实质性问题。

Boundaries

review 期间不要修代码，除非用户明确要求 fix。除非用户明确指示，不要 stage、commit、push、approve、 request changes 或在 GitHub comment。

当这个 skill 在 Gateflow 中使用时，review findings 必须方便 controller 把每项裁决为 accepted、 rejected-with-reason、deferred-with-owner 或 needs-more-evidence。