ethanreedlabs/sulde/multi-source-review

multi-source-review — 多源评审 + 分类决策

Why this skill exists:单 reviewer 实证 critical claim 有失误风险(协议字段名错 / grep 范围漏 / context 偏差)。盲目接受全部 finding = 反向破坏。盲目推翻 = 错过真问题。本 skill 提供实证 + 三角 + 分类决策的可执行流程。

§-1 前置条件(plugin 依赖)

本 skill 引用以下外部 skill / subagent:

依赖处理:Agent 先发现当前宿主已有能力。缺少可选 plugin 时默认用内置审查能力降级；若安装确有材料收益且涉及外部变更，展示宿主原生 Allow/Deny，Allow 后由 Agent 安装并验证。不得把安装命令交给用户。

§0 触发条件

任一命中 → 启动本 skill:

不触发:小 bug fix / 一行改 / 局部 refactor / 临时实验。

§1 第一步:区分代码评估 vs 文档评估

不同目标维度不同,不可混评。

1.1 代码评估维度

1.2 文档评估维度

1.3 混合(代码 + 文档)

实际项目常混(代码改 + doc 同步)。先分,再合:列出代码维度 finding + 文档维度 finding,不要混在同一份 review prompt(reviewer 会顾此失彼)。

§2 第二步:候选 skill / Agent 矩阵(按能力)

启动 review 前先列候选(按 angle / 能力),不要一上来就 spawn 全部。

禁忌:不要一次 spawn ≥4 subagent — 信息过载,你无法消化。

§3 第三步:组合 ROI 推荐 + 让用户选

按 angle 给 候选组合表 + 工时 + ROI 理由,让用户挑(不是抛 N 选 1,是基于实证给推荐 + 备选)。

推荐组合模板

给推荐 + trade-off + 等用户选(不直接 spawn 全部),例:

"推荐 ★ 1 + 2 并行(~25 min)— 元 review process finding + 双 subagent 覆盖代码 + 文档双维度。

若担心单源风险,加 4 三角验证(~10 min);若想拉高看方向 add ★ 1 already 含 zoom-out。

不推荐一次 spawn ≥4 subagent(信息过载消化不了)。

跑 ★ 1+2 还是加 4 三角验证?"

§4 第四步:三角验证铁律(critical claim 必)

单 reviewer 实证 critical claim 不够。任一命中 → 必三角:

三角验证 prompt 模板

独立三角验证 [target] 的 [N] 项 critical claim。**不读本 session 上下文,只看 codebase + 官方 docs 实证**。
 
前 [N] 份 review 给 [M] 项 finding,其中 [K] 项 critical claim:
1. [claim 1]
2. [claim 2]
...
 
前 reviewer 可能偏差:
- reviewer 1: [可能偏差]
- reviewer 2: [可能偏差]
 
三角验证 [K] 项:
### V1. [claim 1]
实证命令:[精确 bash command 或 WebFetch URL]
判定:✅ 真 / ❌ 误 / ⚠️ 部分
 
### V2. ...
 
输出综合判定:[K] 项中真正必修哪几项 / 哪几项 reviewer 误判。

实战教训(本 skill 来源 case)

§5 第五步:用 receiving-code-review 4 类分类 finding

review 结果到手后 不盲目实施 / 不盲目推翻。按 4 类分:

🔴 类 A — 真 bug(无论 context 都修)

• 协议错(JSON 字段名错 / schema 不合规)
• broken reference(引用不存在 file / tag / URL)
• runtime 失败(装上跑必坏)
• 绝对路径写死(换机器坏)
• 安全漏洞

处理:立即修,不需用户确认。

🟡 类 B — Reviewer 缺 context(不修 + 标 reasoning)

• 基于错误假设的 finding(reviewer 不知 audience / 决策边界)
• 跟用户之前决策冲突的"建议"
• 重新发明轮子的"professional feature"(YAGNI)

处理:不修 + 文档/commit message 标 "push back reasoning: reviewer 不了解 [X]"。

不要 performative agreement(避免:"You're absolutely right" / "Great point" / 然后全实施)。

🟠 类 C — 跨决策边界(必用户拍)

• 涉及 architectural decision(public/private / license / scope)
• 涉及 trade-off(性能 vs 可读性 / 短期 vs 长期)
• 涉及第三方影响(团队成员 PII / 已 release 用户兼容)

处理:STOP 实施,列出 trade-off + 推荐路径 + 等用户拍。

🟢 类 D — Nit / 可选(列出供参考)

• 措辞 / 格式
• 风格偏好
• 边缘 edge case

处理:列出,不一定修。若工时短(<5 min)且无害,顺手改。

§6 第六步:跨决策边界识别(stop and discuss)

任何 finding 命中以下 → 停,问用户:

禁忌:reviewer 推荐的 architectural change 绝不直接实施,即使听起来合理。

§7 第七步:输出最终决策矩阵

完成上述步骤后,给用户清晰的 决策矩阵(template):

## 最终决策矩阵(综合 N 份 review + 实证)
 
### 🔴 类 A — 必修(M 项,立即实施)
| # | finding | 实证理由 |
| A1 | ... | ... |
...
 
### 🟡 类 B — 不修(K 项)
| # | finding | push back reasoning |
| B1 | ... | reviewer 缺 [context] |
...
 
### 🟠 类 C — 用户拍(P 项)
| # | finding | 决策路径(P1/P2/P3 + trade-off)|
| C1 | ... | P1: 操作 X, trade-off Y; P2: ... |
...
 
### 🟢 类 D — Nit(Q 项,可选)
- ...
 
## 推荐
基于实证 trade-off,推荐 [路径]。理由:[1-2 句]。

然后:

1. 不等用户:类 A 立即实施(短的 inline,长的下个 message commit)
2. 等用户:类 C 必等拍
3. 不实施:类 B 不修(commit message / doc 内标 reasoning)
4. 可选:类 D 列供参考

§8 反模式(本 skill 防止的 case)

反模式 1:Performative agreement

❌ 看 reviewer finding → "都对!实施!" → 全改 → 引入新 bug + 推翻自己之前决策

✅ 实证每项 → 分 4 类 → 类 A 改 / 类 B 不改 / 类 C 等用户

反模式 2:单源协议实证

❌ 派 1 个 claude-code-guide → "官方说 X 字段" → 信仰 → 实施 → P1 翻车

✅ 派 2 个独立 subagent (或 1 个 + 自己 WebFetch 二次)→ 对比 quote → 一致才信

反模式 3:Reviewer 跨决策边界,盲目接受

❌ reviewer 说"应该 force push rewrite history" → 立即跑 git push --force → 团队炸锅

✅ 识别"force push" = 跨架构边界 → 类 C → 列 trade-off → 等用户拍

反模式 4:代码评估 + 文档评估 混 prompt

❌ "review 这个 PR" → reviewer 顾代码漏 doc / 顾 doc 漏代码

✅ 分两个 prompt:一个聚焦代码(协议 / 安全 / 性能),一个聚焦文档(路径 / 链接 / PII)

反模式 5:数字 / 计数 finding 不自己 grep verify

❌ reviewer 说 "8 处含 X" → 直接信 → 列入修 list

✅ 自己 grep -rln "X" . → 实证后再 list(reviewer 可能漏 grep 范围 / 用错 glob,数字易偏)

§9 触发例(自检该不该用本 skill)

该用

• "我刚把 v0.2.0 设计 doc 改完,review 一下"
• "这个 PR 改了 15 个 file,merge 前 review"
• "现在有什么问题?"(用户主动问)
• "应该 commit + push 吗?"(claim 完工前)

不该用

• "改个 typo"
• "这一行能不能这样写?"
• "解释一下这段代码"

§10 与其他 skill 配合

§11 输出 commit 时

类 A 修复后 commit message 必含:

• review source(哪几个 reviewer / subagent)
• 接受的 finding(哪几项,简号 A1-AN)
• push back 的 finding(哪几项 + reasoning)
• 等用户拍的 finding(哪几项 — commit 时未实施)

真实例(取自一次 plugin v0.1.x review,作为格式参考 — 你的项目用对应 finding 编号填):

fix: address multi-source review findings A1-A7
 
Reviewers: <protocol-review-subagent> + <content-review-subagent> +
<triangulation-subagent>.
 
Accepted (N fixes):
  A1: <finding 1 short description> → <action taken>
  A2: <finding 2> → <action>
  ...
 
Pushed back (M findings):
  B1: "<finding>" — reviewer assumed <X>; user decision: <Y>
  B2: ...
 
Deferred to user decision (K):
  C1: <decision-boundary finding> — see follow-up <doc / issue>

⚠️ 上面是模板示例,不是硬性 require 字段。关键纪律是 3 段:Accepted / Pushed back / Deferred(每个 finding 都要给个明确的"我做了什么")。

Final rule:本 skill 的目的不是"做全所有 review",而是用最少 token + 最准确 finding 出可执行决策。Over-review 也是反模式。