ethanreedlabs/sulde/handoff-code-review

handoff-code-review — 每次 Dev handoff 必跑 4 维 review

Why this skill exists:Dev handoff "shipped" ≠ "对",更不等于"最优"。常规检查只覆盖 build/runtime/visual 表层;架构是否统一 / 复用是否到位 / 非架构问题是否最小改动这 3 维常被遗漏 → 累积技术债 + scope 漂 + 同款 bug 反复。本 skill 强制 4 维过一遍。

不替代 multi-source-review:那是 >10 文件 / 跨模块 / 大决策的重型 review;本 skill 是每次 Dev handoff(通常 1 task / ~几百行)的轻量 review。

§0 触发条件(任一命中即跑)

不触发:doc 起草 / 反抽 / 计划 / 用户问"plan" / 协调端自己 commit。

§1 4 维检查清单(全过 + 表格输出,不可省)

维 1 — 常规检查 ✅ (标准 handoff 验证)

判定:任一缺 → ❌ block + 要求 Dev 补 handoff;全 ✅ → 进维 2。

维 2 — 架构统一 ⭐ (核心)

问:Dev 用的是项目已有 pattern,还是另起炉灶?同款问题用同款解?

判定:

• ✅ 全部走既定 pattern → 进维 3
• 🟡 局部偏离 + Dev §upgrade 已报清楚 → 接受 + handoff escalation
• 🔴 多处自创 pattern / 偏离已知 rule + 未 escalate → ❌ block + 派 fix task

维 3 — 复用 / 抽取复用 ⭐ (反 over-engineer + 反 copy-paste)

问:既有组件 / 工具 / asset 被复用了吗?新建的有没有过度抽取?

判定:

• ✅ 复用充分 + 不过抽 → 进维 4
• 🟡 漏复用 1-2 处(eg 新 asset 应复用)→ 接受 + 记 escalation 后续修
• 🔴 整体 copy-paste 既有逻辑 / 或 1-2 次用强抽 helper → ❌ block + 派 refactor

维 4 — 非架构问题最小最少代码改动 ⭐ (反 scope 漂)

问:小问题用了大改动吗?顺手 fix 其他?out-of-scope 自加?

判定:

• ✅ 改动量与 scope 匹配 + 无顺手 fix → final ✅ ship
• 🟡 1-2 处轻微扩,Dev §upgrade 标 → 接受
• 🔴 显著扩 / 顺手 fix 多 → ❌ block + 退回 task 重做

§2 输出格式(强制)

每次 review 必输出完整 4 维表 + verdict,不可只口头说"OK":

## handoff review:<task slug>
 
| 维 | 1 常规 | 2 架构 | 3 复用 | 4 最小改动 |
|---|:-:|:-:|:-:|:-:|
| 状态 | ✅ | ✅ | 🟡 | ✅ |
| 关键发现 | build OK / log clean | 路由走统一 param API ✅ | 资源 X 应复用,Dev 新迁 | 改动 N file 与 scope 一致 |
 
**verdict**: ✅ merge OK / ⚠️ partial(merge + escalation)/ ❌ block(派 fix task)
 
**escalation 候选(转后续 task)**:
-[ ] 维 N 的 🟡 项 → ...

§3 反模式禁区(自我提醒)

• ❌ Dev handoff "✅ shipped" 就 ack 不实证 4 维 → 同源问题反复
• ❌ 维 2(架构)只看新代码,不交叉验既定 pattern → 偏离累积
• ❌ 维 3 漏复用 audit → 同款 asset / model / component 多次 cp,技术债爆炸
• ❌ 维 4 接受"顺手 fix" 不问理由 → scope 漂传染整个 sprint
• ❌ 不给 verdict / 不写表格 → 用户看不到明确结论,无法决策下一拍

§4 升级路径(本 skill = 默认轻量;多类升级触发)

命名实证注意

• ⚠️ 本 SKILL 名 `handoff-code-review` ≠ session 接力用的 `handoff`;后者是对话压缩 / session 接力,本 SKILL 是单 task 4 维 review
• 部分 skill 设 disable-model-invocation: true(如 zoom-out)→ 协调端改用当前宿主可调用的等价审查能力，不要求用户代触发
• 依赖缺失时由 Agent 发现并降级；确需安装且涉及外部变更时走宿主原生 Allow/Deny，Allow 后由 Agent 安装

串行原则

本 skill 始终先跑(维 1-4 表 + verdict);输出 🟡 / 🔴 后再升级。

• 🟡 多 + 维 4 嫌疑 scope 漂 → grill-me stress-test 真的需要这么多?
• 维 2 多处偏离已知 rule → diagnose 找根因 + zoom-out 拉视角
• 维 2 / 3 🔴 + 大改 → multi-source-review 三角
• 完工前 final → verification-before-completion
• 大架构改 / 跨模块 → 原生计费/高风险 Allow 后由 Agent 启动高阶 review

单 task / 1-2 文件 / <500 行 → 本 skill 单飞,不升级。

与既定 skill 对比(为何不替代)

§5 invoke 时机

• 用户给 handoff path → 立即跑本 skill,不直接派下一拍
• 协调端起新派单前自检 → "上一个 task review 跑过没?" 没跑 → 跑
• 已 push / 已 merge → 仍跑(防 stack 累积偏)

未命中检查项 → handoff §upgrade 报 → 协调端追加到本 skill。

§6 Pre-merge dual-mode gate(per user 反馈 "dark/light mode 总搞错")

UI 还原 / transpile / reimpl 类 task,Dev handoff §视觉对比表必含 light + dark 双 mode 截图比对,each mode ≥ 5 元素 ❌ ≤ 1。

§6.1 双 mode 截图取证 protocol(Dev 端,handoff 必跑)

# Step 1:切 light mode(App 内主题设置切 "亮" 模式)+ 截图归档
#   实现端真机截图 → screenshots/<task>-light.png
 
# Step 2:切 dark mode + 重 capture
#   实现端真机截图 → screenshots/<task>-dark.png
 
# Step 3:真值源同入口 light + dark 截图(user 提供 / 协调端取)
#   screenshots/<task>-truth-light.png + truth-dark.png
 
# Step 4:handoff §视觉对比表 双 mode 各 5 元素

注意主题切换若走 App 内设置(而非系统 toggle),则系统级 uimode 命令不生效 — 按 App 实际主题入口切。

§6.2 handoff §视觉对比表 dual-mode 模板(强制)

## §视觉对比表(dual-mode each ≥ 5 元素)
 
### Light mode
 
| # | 元素 | 真值源 ref | 实现端真机 | 一致? |
|:-:|---|---|---|:-:|
| 1 | page bg `#FDFBF7` | `<page>.dart:80` light | screenshots/<task>-light.png 顶部 | ✅ |
| 2 | notice card bg `#FFFCF8` | line 92 light | 同 | ✅ |
| ... | ... | ... | ... | ✅ / ❌ |
 
### Dark mode
 
| # | 元素 | 真值源 ref | 实现端真机 | 一致? |
|:-:|---|---|---|:-:|
| 1 | page bg `#111111` | `<page>.dart:80` dark | screenshots/<task>-dark.png 顶部 | ✅ |
| 2 | notice card bg `#1F1F1F` | line 92 dark | 同 | ✅ |
| ... | ... | ... | ... | ✅ / ❌ |

§6.3 协调端 review verdict 判定

§6.4 反例实证

历史:多个 polish 迭代页面因 dark mode 色值反差不足反复返工;多卡 light/dark bg 多次 fix — Dev 仅给 light 截图,user 真机切 dark mode 看才发现 issue。

→ 本 §6 强 enforce 后,Dev handoff 一开始就含 dual-mode 截图,协调端 review 一拍 verdict,不返工。

§7 protocol 演进

• v1.0:初版 4 维 review(常规 / 架构 / 复用 / 最小改动)
• v1.1:维 1 强化 dual-mode 截图 + 新增 §6 Pre-merge dual-mode gate(per user 反馈"dark/light mode 总搞错"+ polish 反例)

下次升版触发:user 新反馈 + Dev handoff 实战发现未命中 review 维度。