code-review-adversarial

Deep code review engine that dispatches a committee of specialized reviewers, converges their findings, and outputs a structured verdict. PR-type-aware: feature PRs are evaluated for better alternatives; bugfix PRs are evaluated for fix correctness + regression introduction.

Design doc: DESIGN.md (in this skill's directory) — full design rationale, research references, and decision records.

Reference files (loaded on demand):

• references/type-playbooks.md — per-PR-type review checklists
• references/reviewer-personas.md — reviewer persona prompt templates
• references/convergence-protocol.md — convergence and arbitration rules

When to use

• High-stakes PR: concurrency, security, API/contract changes
• User explicitly asks for adversarial / multi-agent / deep review
• Feature PR where solution quality matters (is there a better approach?)
• Bugfix PR where correctness and regression risk matter

When NOT to use

• Routine PR quick pass (use a single reviewer)
• Pure merge/rebase with no logic changes
• User wants fast feedback, not deep analysis (this is expensive: 2-4 sub-agents)

Arguments

Parse $ARGUMENTS loosely:

• PR target (required): PR #<N>, #<N>, <N>, or full PR URL (GitHub/GitLab/Gitea).
• reviewers:<comma-list> — manually specify personas (overrides type-based auto-selection). Accepted tokens: design, correctness, security, root-cause, regression, behavior, test-coverage, perf, devils-advocate.
• devils-advocate or --devils-advocate — enable devil's advocate persona (high-stakes PRs).
• max-rounds:<N> — convergence round limit (default: 2).
• format:<markdown|json|comment> — output mode (default: markdown). comment asks user before posting.
• pr-type:<type> — manually specify PR type, overrides auto-classification. Accepted: feature, bugfix, refactor, performance, chore, docs, test.

If $ARGUMENTS is empty, stop and ask the user for a PR number or diff.

Workflow

Phase 0: Baseline（基线锁定）

确定 PR 真正改了哪些文件，防止 diff 污染。产出 correct-diff.patch 作为所有 reviewer 的评审基线。Phase 0 不限制 reviewer 能探索哪些文件——那是自由探索（Phase 2）。

基线必须 unpolluted — 如果连评审对象都搞错了，后面所有评审都是空中楼阁。

1. Fetch PR metadata. Use your platform's CLI or API (gh pr, tea pr, GitLab API, etc.) → base ref, head ref, title, labels, body, changed_files count.
2. Lock merge-base (critical — prevents diff pollution):

   git fetch origin "$BASE_REF" "$HEAD_REF"
   BASE=$(git merge-base origin/"$BASE_REF" origin/"$HEAD_REF")

3. Generate correct diff (two-dot, NOT three-dot):

   git diff "$BASE..origin/$HEAD_REF" > /tmp/<pr>/correct-diff.patch

4. Verify file count matches PR metadata:

   git diff --name-only "$BASE..origin/$HEAD_REF" | wc -l
   # Must match changed_files from the PR metadata. Mismatch → abort, report anomaly.

Hard constraints:

• NEVER use origin/base...origin/head (three-dot symmetric diff). Use merge-base two-dot only.
• File count mismatch → abort, report the discrepancy.

Output: correct-diff.patch — the clean review baseline, passed to all reviewers.

Phase 1: PR Type Classification

Goal: Determine PR type → select reviewer personas + load checklist.

Classification (priority descending):

1. PR labels: contains bug → bugfix; contains feature → feature
2. Conventional Commits prefix: feat/fix/refactor/perf/chore/docs/test
3. PR title keywords: "fix"/"修复" → bugfix; "add"/"新增"/"feat" → feature
4. Diff analysis: if existing tests modified (not new test files) → reclassify as feature/bugfix (refactor must not change test behavior)

Design-heavy detection:

DESIGN_LINES=$(git diff "$BASE..origin/$HEAD_REF" -- '*.proto' '*.md' | grep -cE '^[+-]')
IMPL_LINES=$(git diff "$BASE..origin/$HEAD_REF" -- '*.go' '*.ts' '*.py' '*.java' '*.rs' | grep -cE '^[+-]')
# proto+md 占比 > 70% 且实现代码 < 30% → design-heavy: true

Persona selection: 按类型和 design-heavy 选角色。权威映射表（含 design-heavy override）在 references/reviewer-personas.md 的「角色与 PR 类型的映射速查」章节——读那里，不在这里重复。每个选中的 persona 读 references/personas/<name>.md。

Fallback: unrecognized types → use feature's personas (strictest).

Output: pr_type + design-heavy: bool + selected persona list + loaded checklist from references/type-playbooks.md.

Phase 2: Reviewer Dispatch

Goal: Dispatch persona committee in parallel. Each persona covers one dimension.

Prompt assembly — 固定内容在前，变化内容在后（最大化 prompt cache 命中）:

[1. 通用约束]        ← 共享前缀（所有角色相同），from references/reviewer-personas.md
[2. correct-diff.patch]  ← 共享前缀
[3. PR 元数据]       ← 共享前缀（title / description / issue link）
[4. personas/<name>.md]  ← 变化部分，放最后。只读该角色文件

Dispatch: Use the Agent tool to launch all selected personas in parallel (multiple tool calls in one message). Each agent gets:

• The assembled prompt (通用约束 + diff + 元数据 + 角色专有)
• correct-diff.patch content as review baseline
• PR metadata (title, description, issue link if any)
• Repo path for free exploration

Output schema (each reviewer returns this — 8 fields, enforced):

{
  "persona": "<role-name>",
  "verdict": "ready | ready-with-fixes | not-ready",
  "findings": [
    {
      "severity": "P0|P1|P2|P3",
      "type": "correctness|design|security|root-cause|regression",
      "file": "<path>",
      "line": <N>,
      "issue": "<one-line description>",
      "evidence": "<file:line + reasoning>",
      "confidence": <1-10>
    }
  ],
  "verified_correct": ["<confirmed-correct points>"]
}

in_diff / finding_category etc. are NOT filled by reviewers — Triage Filter (Phase 3) determines them automatically from file paths.

Phase 3: Triage Filter

Goal: Discard invalid findings before convergence. Every surviving finding must be diff-anchored — it either points at a diff line, or proves the diff broke something outside it. Findings that float free of the diff are noise; drop them.

Step 1: Infer component scope

# Infer components from diff file paths
git diff --name-only "$BASE..origin/$HEAD_REF" | \
  sed 's|^\([^/]*\)/.*|\1|' | sort -u
# Example: api bss dashboard
#
# Further细分 (e.g. dashboard → backend / ui):
# api/                          → api
# bss/bss-invoice-service/      → bss-invoice-service
# dashboard/dashboard-backend/  → dashboard-backend

Output: component-scope set (e.g. {api, bss-invoice-service, dashboard-backend}).

Step 2: Apply discard rules

Two scope rules — the distinction:

• component out-of-scope: file belongs to a completely unrelated component (backend PR reviewing frontend) → discard regardless of finding type. This is the PR's semantic boundary.
• scope violation: file is outside diff but within a related component → only discard "improvement" type; keep "diffusion-impact" type. This allows reviewers to catch "the diff broke another file in the same component".

Design-heavy 补充规则: 当 design-heavy: true 时，「implementation-speculation」规则激活——丢弃所有对「尚未存在的实现行为」的推测性 finding。保留契约层 finding（兼容性、命名、字段编号、AIP 合规、错误码完备性）。判据：finding 引用的文件是 .proto/.md/接口定义 → 保留；引用的是 .go/.ts 等实现文件且该文件不在 diff 内（说明实现还没写）→ 丢弃。

Output: surviving findings + discarded findings (with discard reason, for transparency).

Phase 4: Convergence

Goal: Converge multiple reviewers' surviving findings into a consistent verdict.

Every verdict and finding disposition must be evidence-bound — backed by a file:line citation the coordinator can verify. No evidence, no verdict. Load references/convergence-protocol.md for full rules. Summary:

Step 1: Build finding matrix

Group all surviving findings by "same issue" (same file:line + same defect).

Step 2: Converge by group type

Step 3: Arbitrate conflicts

Coordinator reads code, independently judges. If code facts are insufficient → convergence round (Step 4).

Step 4: Convergence round (if needed)

1. Prefer SendMessage to wake surviving agents (saves tokens, preserves context).
2. If agent terminated → re-dispatch via Agent tool with coordinator's ruling + conflict summary + code locations as new prompt.
3. Send the convergence-round prompt template (from references/convergence-protocol.md).
4. Guardrails: max 2 rounds (default). Check stability after each round. Unresolved at limit → label "unresolved", list both sides, don't force-merge.

Step 5: Determine verdict

Count surviving findings (post-Triage + post-Convergence):

has P0              → not-ready
has P1, no P0       → ready-with-fixes
only P2/P3          → ready-with-fixes
no findings         → ready

Convergence complete when: all surviving findings have a disposition (fix-in-pr / followup / rejected) AND all conflicts are arbitrated AND unresolved disagreements (if any) are explicitly labeled.

Output

Based on format argument:

format: markdown (default)

产出评审报告的 markdown 文本，返回给调用方。不自动发 PR comment。 如果调用方想把报告发到 PR，由调用方决定，或用 AskUserQuestion 询问用户后再发。

format: json

Return structured JSON to the caller (no PR comment posted):

{
  "pr_type": "<type>",
  "verdict": "<ready|ready-with-fixes|not-ready>",
  "reviewers": [{"persona": "...", "verdict": "...", "findings_count": N}],
  "findings": [
    {
      "id": "F1",
      "severity": "P1",
      "type": "root-cause",
      "persona": "root-cause-auditor",
      "file": "...",
      "line": N,
      "issue": "...",
      "disposition": "fix-in-pr|followup|rejected",
      "consensus": "independent|intersection|arbiter-ruled|unresolved",
      "confidence": N
    }
  ],
  "triage": {"discarded": [{"reason": "...", "detail": "..."}]},
  "convergence": {"rounds": N, "conflicts_resolved": N, "unresolved": []}
}

format: comment

产出精简 markdown 并询问用户确认后再发 PR comment。绝不自动发布。

硬约束: 必须先用 AskUserQuestion 询问用户「是否将评审报告发布到 PR？」，用户确认后才发。用户拒绝则只返回报告文本。

报告模板（精简版，只含决策必需信息）:

## 对抗评审报告

**Verdict**: <ready/ready-with-fixes/not-ready>（PR 类型: <type>，置信度: <high/medium/low>）

### Finding 表
| # | 严重度 | 位置 | 问题 | 处理 |
|---|--------|------|------|------|

（如有 P0/P1 冲突仲裁）
- <finding> → <裁决>：<一句话理由>

（如仅 P2/P3）
> 残留 <N> 项 P2/P3（<类型>），建议 follow-up 跟踪，不阻塞合入。

Safety rules

• Never auto-comment to PR. Default format is markdown (return text only). Even in format: comment mode, you MUST ask the user via AskUserQuestion before posting. The user says no → return text only.
• Do not merge unless the user explicitly asks AND verdict is ready/ready-with-fixes AND all blocking findings are addressed.
• Do not push fixes to someone else's PR.
• Worktree cleanliness: never switch branches on a dirty tree.
• Diff baseline integrity: Phase 0's merge-base lock is non-negotiable. If you can't verify the file count, stop and report.

Parameters

Design rationale

Full design decisions and research references: see DESIGN.md §2 (in this skill's directory).