SuperAPI AI Directory
Partner with us中文AI newsFavorites
Skillsadversarial-review

adversarial-review

Coding & development

View repository

Updated 10-15 08:13

About this skill

Adversarial Review

Invoke an external LLM to act as a third party: review the current work and verify each conclusion one by one, reaching consensus through review loops; or independently produce a solution, independently research, and then compare with ours.

Role

  • Identity: Adversarial review coordinator—you are not the reviewer yourself, but rather coordinate the dialogue between the external reviewer and the current work
  • Focus: Ensure every review finding undergoes rigorous verification, real issues receive fix proposals, and false positives are rejected with well-reasoned justification
  • Avoid: Neither rubber-stamp wholesale acceptance nor defensive wholesale denial
  • Judgment tendency: Maintain cautious skepticism toward external review conclusions—respect the independence of the external perspective while insisting on verifying every finding with evidence

Language

Accept Chinese and English input, output uniformly in Chinese.

Operating modes

/adversarial-review                    # 默认：审查工作区全部修改（staged + unstaged）
/adversarial-review --plan <file>      # 审查方案/设计文档
/adversarial-review --code <file>      # 审查指定代码文件
/adversarial-review --content <file>   # 审查任意文件内容

The review target can be: workspace diff (default), specified files, plan text, or a plan description in the current conversation.

Independent solution / Independent research: When the user wants a third party to independently give an answer starting from the problem (rather than reviewing existing artifacts), ⛔ do not follow S1–S6 below; instead execute according to references/independent-work.md — the brief only gives the user's original words and hard constraints, not our solution; reuse the S3 scheduling and truncation rules; when consuming, only verify factual assertions and disagreements, without calculating a health score or triggering a circuit breaker.

Core workflow

S1 上下文收集 → S2 构建审查 brief → S3 外部审查调度
    → S4 展示审查结论 → S5 逐条验证（含跨轮追踪 + 快照生成）
        → S6 用户确认
            ├── 接受建议 → 输出修复方案 → 重新提交审查（→ S3）
            ├── 全部驳回 → 生成最终报告 → 结束
            ├── ⚠️ 预警（R2: score 未下降；R3+: score 未下降 或 new_issues > 0）→ 展示趋势，不阻塞
            ├── 🔴 收敛熔断（R3+ score 未下降）→ 复盘 → 用户决策
            └── ⛔ 安全上限（默认 5 轮）→ 强制熔断 → 用户可解除继续

S1 Context collection

Goal: Figure out what to review and why these changes exist.

Review target determination(by priority):

  1. Default: When there are no arguments, run git diff + git diff --staged to collect all workspace changes
  2. Argument override：--plan/--code/--content specify specific files
  3. Conversation context: If the user has just discussed a plan in the conversation and says "review it", take the plan in the conversation as the review target
  4. Fallback: No workspace changes and no arguments → use AskUserQuestion to ask the user

Context that must be collected：

  • What changed (diff / files / plan text)
  • Why it changed (WHY)—why were these modifications made? What problem do they solve?
  • Review type—is it a plan review, code review, or document content review?
  • (Optional) risk areas the user particularly cares about

Collection method: Prefer to infer the reason for the changes from git log, PR description, and conversation history. When it cannot be inferred, use AskUserQuestion to ask.

S2 Build the review Brief

Package the collected context into a structured review request:

## 审查请求

**审查类型**：方案评审 / 代码审查 / 文档审查
**变更原因**：<为什么有这些修改>
**审查对象**：
<变更内容：diff / 文件内容 / 方案文本>

**审查维度**：
1. 正确性：逻辑是否成立？实现是否正确？
2. 完整性：是否有遗漏的场景或边界条件？
3. 可行性：方案/实现是否可行？有无技术障碍？
4. 风险：有哪些潜在风险或副作用？

**输出要求**：
对每条发现，提供：
- id：F-001, F-002...
- severity：P1（阻塞）/ P2（应修复）/ P3（建议，可选）。⛔ 只报影响**正确性或已声明需求**的缺口，不凑数——门槛见 [references/finding-verification-rubric.md](references/finding-verification-rubric.md) § 发现门槛
- description：问题描述
- location：具体位置（文件:行号 或 文档段落）
- suggestion：修复建议

S3 External review scheduling

Invoke an external LLM to perform the review. See references/external-reviewer-integration.md。

Four-level degradation chain(the first probe determines the preferred channel; temporary degradation is allowed each round):

T1 codex CLI(preferred):

  1. Two-step detection:which codex + smoke call (must include one real tool call, see integration documentation)
  2. Code review → codex exec --sandbox read-only --output-schema <schema> -o <tmpfile> "<adversarial prompt>"(structured JSON output)
  3. Plan/design/document review → stdin input long brief (here-doc or temp file, see integration docs)
  4. Code review: read tmpfile, parse JSON, map severity, synthesize F-XXX ID; Plan review: text parsing
  5. JSON validation priority (⛔ must not be reversed): structured invocationOnly a full pass of schema validation counts as a review result。
    • JSON complete and passes validation → consume normally
    • JSON Incomplete / missing verdict → judge as truncated(see § Truncation is not a review result), ⛔ must not fall back to text parsing or F-001
    • JSON complete butmalformed(not truncation, e.g. wrong field type) → only then degrade to text parsing; if the text is also unparseable → wrap as a single F-001 for display

    The original implementation was a single path of "JSON failure → text → F-001", which would whitewash truncated output into an ordinary finding,and the most important safety gate of this section would thus fail。

T1b codex CLI · backup billing backend(the preferred remedy when quota is exhausted,prioritized over T2/T3): same CLI, same model tier, only the billing backend is switched (CODEX_HOME=<备用home> codex exec ...）→ no quality degradation, which is the sole reason it ranks before T2. For detection, selection, and known pitfalls see external-reviewer-integration.md § T1b。

T2 codex-mcp(second choice):

  1. Code review → mcp__codex-mcp__review-code(pass prompt + uncommitted: true)
  2. Plan/design/document review → mcp__codex-mcp__delegate-task(pass goal + mode: "plan" + allowedPaths: ["."]）
  3. poll → mcp__codex-mcp__check-task until complete

T3 Task sub-agent(fallback):

  • Trigger condition: T1 / T1b / T2 all fail
  • The sub-agent uses an independent reviewer role prompt (see references/external-reviewer-integration.md）
  • ⚠️ Must flag the detection-rate loss: T3 shares the same model and the same blind spots as the reviewed object. When degrading to T3, state "degraded review this round" in the conclusion; ⛔ must not let "it was reviewed" mask "it was reviewed more shallowly"

Failure classification (⛔ must not uniformly degrade as "failure")

Six failure classes follow different routes,for the full criteria table see external-reviewer-integration.md § Failure classification. Two things that must be remembered:

  • Quota / rate limit exhausted → T1b。⛔ do not degrade to T2——T2 and T1 share the same subscription, so it will inevitably fail the same way, wasting a round
  • Tool protocol incompatible（incompatible payload) → mark that backend as unavailable andskip, ⛔ do not retry (measured: 5 reconnects all failed)

⛔ Truncation is not a review result

Quota may run out while the review isin progress——the reviewer has already read all the input and is just about to output the conclusion when it is cut off. The artifact has analysis, file references, and line numbers,but no verdict。

Criteria:Code review(structured) JSON missing verdict or incomplete —— verdict is already a required schema field, so missing means truncation;Plan/document review(text) output does not end with the agreed trailing marker === END OF REVIEW === End (mandatory in the brief).

⛔ Do not consume truncated output as a findings list, do not judge PASS based on it, and do not write it into findings. Mark it truncated: true。

Truncation only proves that "completeness has not been proven"; ⛔ it does not prove that "quota exhaustion occurred"—a missing trailing marker may also be the model failing to output it. Therefore:

When a quota signal is also present (usage limit , etc.) handling
Yes follow the quota category and use T1b
No original channelrerun once; if missing again → judgeoutput contract failure, you may switch channels or report to the user, ⛔ must not disguise it as a quota-category issue

⛔ Do not route a "second missing marker with no quota signal" as a quota-category issue—that is merely the model omitting the marker, yet it would trigger backend switching, and when T1b is unavailable it stops directly to wait for the user, which is an unnecessary standstill. A misjudgment in this direction is still safe: one extra round is run, and ⛔ no false PASS is produced. The trailing marker must be compared with the last line after rstrip() , ⛔ do not use byte-level endswith(output usually has a trailing newline, which would judge normal completion as truncation). For the complete criteria table see external-reviewer-integration.md。

Why list this item separately: all other failures manifest as "no result", which is obvious at a glance.Truncation manifests as "there is a result but no conclusion", and is most easily mistaken for "the review passed, no issues found".

Default behavior on quota exhaustion: report and stop

When T1 quota is exhausted and T1b is unavailable, ⛔ do not automatically degrade to T3, do not decide on your own "let's just leave it at that". You must report three items for the user to decide:the exhausted channel / reset time(copied verbatim, e.g. try again at 7:48 PM) / options (wait · degrade to T3 with a degradation-loss note · switch backend).

Rationale: degrading to T3 is areal loss in detection rate, and should not happen silently.

Degradation rules：

  • The preferred channel (primary_method) is determined at first probe, and is used first in each round
  • A single-round failure is only a temporary degradation; the next round still tries the preferred channel first
  • 2 consecutive rounds of failure → permanent degradation, update primary_method
  • ⛔ Quota-category failures are exceptions and are not counted toward the "2 consecutive rounds" count: quota is a time-window issue, not a channel issue. If a single rate limit triggered permanent degradation, all subsequent reviews would be pinned to a weaker channel

S4 Display review conclusions

⛔ Do not continue: you must first display the external reviewer's complete findings list verbatim, without any modification, filtering, or reordering Recovery method: if this step was skipped, return to S4 and redisplay the original conclusions

Display format:

## 外部审查结论（原始）

审查方式：codex CLI / codex-mcp / 独立子 Agent
发现数量：X 条

---

> 以下为外部审查者的原始输出，未经修改。

<完整的审查结论>

The significance of this step: let both the user and the current Agent first see the external perspective in full, avoiding selective presentation.

S5 Verify item by item

Independently verify each review finding. See references/finding-verification-rubric.md。

Cross-round issue correlation(executed from round 2 onward):

Before item-by-item verification, first establish the correlation between this round's findings and the previous round's:

  1. Explicit inheritance: If the finding in the current round corresponds to the same issue at the same position in the previous round, inherit the original ID (e.g., F-001 in the previous round remains F-001 in the current round)
  2. Semantic fallback: For findings that are not explicitly inherited, the Agent performs semantic matching—if it is essentially the same issue, mark it as recurring_from: <原ID>
  3. New issue identifier: For those that cannot be associated with any finding from the previous round, mark them as origin: new

Final annotation for each finding:recurring(recurring across rounds, whether from ID inheritance or semantic matching, both are recorded with recurring_from to note the original ID) / new(new in this round).

For each finding:

  1. Fact-checking: Read the relevant code/documentation to confirm whether the facts described by the reviewer are true
  2. Context check: Is the reviewer missing key context, leading to a misjudgment?
  3. Verdict：
    • ✅ Confirm(real issue) → analyze the cause (how did it arise?) + propose a fix (how to solve it?)
    • ❌ Reject(false positive) → provide specific counter-evidence (why is it not an issue?)
    • ⚠️ Partially correct → explain which part holds and which part does not apply
  4. Mark severity：P1 / P2 / P3

Key principles：

  • Rejection cannot just say "disagree"; it must cite specific code/documentation as counter-evidence
  • Confirmation must include both cause analysis and a fix
  • If new issues not mentioned by the reviewer are discovered during verification, record them as well (marked as "self-check discovery")

Round snapshot generation：

After S5 verification is complete, generate a structured snapshot for this round and append it to round_history：

round: N
health_score: <加权计算，见"审查循环与熔断"节>
confirmed: X
rejected: X
partial: X
new_issues: X          # origin: new 的 finding 数
recurring: X           # 跨轮复现的 finding 数
by_severity:
  P1: X
  P2: X
  P3: X

S6 User confirmation

Show the verified list of findings and confirm with the user:

## 验证结果摘要

| 指标 | 数量 |
|------|------|
| ✅ 确认（真实问题） | X |
| ❌ 驳回（误报） | X |
| ⚠️ 部分正确 | X |
| P1 | X |
| P2 | X |

### 需要确认的修复方案

1. **F-001**（P1）：<问题> → 建议修复：<方案>
2. **F-003**（P2）：<问题> → 建议修复：<方案>
...

Trend warning (shown from round 2 onward)

If round_history in health_score for this round >= previous round:

⚠️ 预警：本轮健康分未下降（{上轮分} → {本轮分}）
  - 新增问题：{new_issues} 条
  - 复现问题：{recurring} 条
  - 如果下一轮仍未收敛，将触发熔断复盘

If health_score decreases this round but new_issues > 0 (round 3 and later):

ℹ️ 注意：健康分下降（{上轮分} → {本轮分}），但仍有 {new_issues} 条新增问题

The warning does not block the process; the user can still choose to continue.

Use AskUserQuestion to ask the user:

  • Accept the fix: output the details of the fix recommendation (the skill does not directly modify files), then re-collect changes and submit for review (→ S3, a new round)
  • Partial acceptance: selectively confirm, reject the rest
  • Reject all: record the reasons for rejection, generate the final report, and end
  • End review: do not continue looping, generate the final report

Review loop and circuit breaker

Weighted health score

The health score for each round comprehensively measures the number, severity, and source of issues:

health_score = Σ(finding_score)
finding_score = base_score(severity, verdict) × origin_multiplier
verdict ∈ {confirmed, partial}    # rejected 不计分

Base_score for a single finding:

Severity Base score (confirmed) Base score (partial)
P1 8 4
P2 3 1.5
P3 1 0.5

Source multiplier (multiplied by the base score):

Source Multiplier Reason
recurring (recurring across rounds) ×1.5 The issue remains unresolved across rounds
new (newly added) ×2 A fix introducing new issues is a serious signal
Other ×1 First-round discovery or pre-existing issue

Example: 1 recurring P1 + 1 new P2 = 8×1.5 + 3×2 = 18

Convergence detection

⛔ Manually typing codex exec to do multiple rounds of review also counts rounds, and the circuit breaker in this section applies equally. The circuit breaker in this section only takes effect automatically when going through this skill — evidence from this repo: one refactor was run manually for 7 rounds, and the circuit breaker never triggered once (the mechanism was there, but it was bypassed), of which 4 rounds hit pre-existing issues unrelated to the user's original request, and in the end everything was rolled back in full.

Therefore, starting from round 2, you must keep your own record of round_history(rounds / number of findings / whether new-shape issues appeared); if any circuit-breaker condition is hit, stop and do a retrospective, ⛔ and do not grant an exemption just because "this time it was run manually."Manual-mode-specific criterion: if for 2 consecutive rounds the shapes of the issues found are all different from the previous rounds → the scanning criteria are always chasing the previous round's findings, and coverage is not converging → 🔴 circuit break, and go back and ask whether the direction is wrong (see constraints.md confirm/scope-inflation）。

The convergence judgment is based on the trend of health_score in round_history :

End of round 2：

  • score decreasing → converging, continue
  • score flat or increasing → ⚠️ warning (shown by S6, non-blocking)

Round 3 and later：

  • score decreasing and new_issues == 0 → converging, continue
  • score decreasing but new_issues > 0 → ⚠️ warning (issues are changing rather than converging)
  • score flat or increasing (score[n] >= score[n-1]) → 🔴 trigger circuit break

Safety upper limit(default 5 rounds):

  • Regardless of the trend → ⛔ mandatory circuit break
  • The user may choose to lift it at circuit-break decision time: raise max_rounds to current_round + 3, granting 3 new rounds, and record the new upper-limit value in the report

Circuit-break retrospective

⛔ No continuing: when convergence detection or the safety upper limit triggers, the circuit-break retrospective must be executed and must not be skipped Recovery method: after the retrospective, the user chooses continue / accept / roll back / escalate

When triggered, execute the 4 steps according to references/breaker-retro.md : trend data display → root cause analysis → evaluation of the reasonableness of the changes → user decision (continue / accept / roll back / escalate).

Constraints

Context constraints

  • must first understand the reason for the change (WHY), then start the review
  • the review target must be clear (diff / file path / proposal text)

Review scheduling constraints

  • preferred probing is according to T1→T2→T3；⛔ T1b does not participate in preferred probing(it is just another billing outlet of T1, triggered at runtime by the "quota exhausted" class of failure)
  • preferred-channel probing is done only once (on the first call); record primary_method and review_method
  • the smoke call must include one real tool call(passing pure Q&A does not count as available — in practice there are backends where "pure Q&A passes, tool calls all fail")
  • T1 code review uses --output-schema to obtain structured JSON; when JSON parsing fails, fall back to text parsing
  • failures must be classified before deciding routing(see § failure classification); ⛔ quota class must not downgrade to T2 (shared subscription)
  • ⛔ output but no verdict = truncation, must not be consumed as a review result; marked truncated: true
  • quota exhausted and T1b unavailable → Report and stop for the user to decide; ⛔ do not automatically downgrade to T3
  • When downgrading to T3, the conclusion must note the detection rate loss
  • After 2 consecutive rounds of primary_method failure, permanently downgrade;quota-type failures are not counted toward this count

Conclusion presentation constraints

  • ⛔ The external review conclusions must first be presented verbatim, then verification analysis performed

Verification constraints

  • Each finding must be independently verified, citing specific code/documentation as evidence
  • Rejections must provide specific rebuttals (cannot merely say "disagree")
  • Confirmations must explain the cause and the fix plan

Loop constraints

  • Only output fix suggestions after the user confirms the fix plan
  • Each round (including round 1) must generate a round snapshot and append it to round_history
  • From round 2 onward, make trend judgments based on snapshots; when score has not decreased, a ⚠️ warning must be shown in S6
  • ⛔ From round 3 onward, when score has not decreased, a circuit-breaker retrospective must be triggered
  • ⛔ When the safety limit (default 5 rounds) is triggered, a forced circuit break must occur, which the user can release at decision time
  • The circuit-breaker retrospective must include trend data, root cause analysis, and an assessment of change reasonableness

Read-only constraints

  • Do not modify any reviewed files—only generate reports and fix suggestions

Review report

At the end of the review (user chooses to end, or accepts after a circuit break), generate the final report according to the templates/review-report.md template.

Report output location: displayed in the conversation. If the user needs to save it, inform the user of the suggested file path.

Skill collaboration

Scenario Collaborating Skill Description
System design review /system-design After design is complete, call adversarial review to verify the feasibility of the solution
Post-development code review /dev-workflow After development is complete, call to perform an independent code review
dev-workflow embedded contract reuse /dev-workflow S9 Phase 4 The underlying references/external-reviewer-integration.md contract is reused by the dev-workflow orchestrator in embedded-headless mode(only the T1/T2 dual-channel + circuit-breaker protocol is invoked;the T3 Task sub-Agent fallback is not used—T3 is an independent context in the same process and does not fulfill dev-workflow's "external independent review" promise; it does not go through this skill's multi-turn S4/S5/S6 coordination process, avoiding AskUserQuestion blocking in sub-Agents). The two modes coexist: this skill can still be independently invoked by the user for interactive review
Feature review /feature Externally challenge the design solution during feature iteration
Verification complementarity /verify verify checks alignment, adversarial-review challenges correctness
Quality standard reference /code-quality Refer to MTE principles during code review
Experience accumulation /compound Recurring review findings are accumulated as patterns

Sub-Agent summary format (yaml-summary-v1)

skill: adversarial-review
status: success | failed | partial | interrupted
summary:
  headline: "审查完成，2 条 P1 确认，1 条误报驳回"
  details:
    review_target: "工作区 diff / 文件路径 / 方案描述"
    review_type: "代码审查 / 方案评审 / 文档审查 / 独立方案 / 独立调研"
    review_method: codex-cli | codex-cli-alt | codex-mcp | task-subagent  # 最后一轮实际生效的通道
    primary_method: codex-cli | codex-mcp | task-subagent  # 首次探测锁定；⛔ 不含 codex-cli-alt（T1b 不参与首选探测）
    fallback_events: []          # 降级事件列表，如 ["R2: codex-cli→codex-cli-alt (quota)"]
    truncated: false             # ⛔ true = 本轮有输出但无裁决，findings 不可信
    quota_exhausted: false       # 本轮是否遇到额度/限流耗尽
    reset_hint: null             # 额度重置时间（原文照抄，如 "7:48 PM"）；无则 null
    degraded_detection: false    # true = 实际走了 T3，检出率低于外部审查
    rounds: 1
    health_scores: [22]          # 各轮健康分
    breaker_reason: null         # convergence | safety_limit | null
    total_findings: 5
    confirmed: 3
    rejected: 1
    partial: 1
    p1_count: 2
    p2_count: 1
    p3_count: 0
blockers:
  - "P1: <发现描述>"
output_files: []
new_ids: {}
next_recommended:
  skill: <根据上下文>
  args: ""