adversarial-review
Use when asked for an adversarial review, dual review, mutual-critique review, cross-critique review, or 相互批判レビュー of code (a working diff, a PR, or a whole codebase), or when a review needs higher confidence than a single reviewer gives — before a risky merge or release, or when a prior single review produced inflated severities or generic checklist findings. Also use to verify fixes made in response to such a review.
- License 许可
- MIT
- 最近更新
- 2026-11-15
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- adversarial-review
- description
- Use when asked for an adversarial review, dual review, mutual-critique review, cross-critique review, or 相互批判レビュー of code (a working diff, a PR, or a whole codebase), or when a review needs higher confidence than a single reviewer gives — before a risky merge or release, or when a prior single review produced inflated severities or generic checklist findings. Also use to verify fixes made in response to such a review.
02 资源文件 3
- 参考文档README.md2.4 KB
- 参考文档references/reviewer-prompts.md9.4 KB
- 参考文档templates/report-template.md4.7 KB
03 SKILL.md 正文
Adversarial Review (two-reviewer mutual critique)
Overview
Two reviewers with disjoint lenses review the target blind. Each then attacks the other's findings with per-finding verdicts. The orchestrator synthesizes one report, and fixes are later verified by a fresh-context reviewer. The cross-critique and the fresh verification are what catch severity inflation, generic-checklist findings, over-engineered fixes, and errors inside the fixes themselves — failure modes a single review cannot see.
Core principle: every claim needs file:line evidence, and silence must be auditable — reviewers state what they checked and found clean.
When to Use
- Pre-merge review of a risky diff or PR; audit of a codebase or subsystem
- After such a review, to verify the fixes (Phase R)
- NOT for small routine diffs — a single review is cheaper and enough
- NOT for sdd-forge SDD gate reviews (spec/impl/task-review-loop have their own deterministic contracts)
Protocol
Copy-paste reviewer prompts: references/reviewer-prompts.md. Report structure: templates/report-template.md.
| Phase | Actor | What happens |
|---|---|---|
| 0 Scope | Orchestrator | Pin the target (diff / PR / paths) and commit hash; gather codebase context (scale, deployment reality, house rules such as AGENTS.md); note optional focus areas; fill the prompt placeholders. |
| 1 Blind review | Reviewers A + B in parallel | A = design / maintainability / readability (senior architect). B = security / testing / operational risk. Spawn both with the Agent tool in ONE message (background). Neither sees the other's output. |
| 2 Cross-critique | Same two agents, resumed | SendMessage each reviewer the other's full report verbatim (context preserved — no re-reading cost). Per finding: SUPPORT / PROPOSE-SEVERITY-CHANGE / PROPOSE-REJECT / SUPPLEMENT, each with file:line evidence. Fix proposals are critiqued separately from findings. New findings get IDs A-C1…, B-C1… |
| 3 Synthesis | Orchestrator (main context) | Adopt or reject every finding with a stated reason; set final severity; merge converging IDs (e.g. A-6+B-C2); union the verified non-findings; write the phased remediation plan with a TODO checklist. Rejected findings stay in the report with the rejection reason. |
| R Fix verification | NEW agent, fresh context | After fixes land: spawn a reviewer with no prior involvement. Input = adopted findings + the fix diff only. It re-verifies each fix at file:line and checks every factual claim in the fix text (counts, ratios, "all N sites"). Never verify fixes in the context that wrote them. |
Iron rules — in every reviewer prompt, never trimmed
The prompt templates already contain these; they are the source of the protocol's effectiveness.
- file:line evidence only — cite only lines actually read this session; a finding without evidence is invalid, not "low confidence"
- Verified non-findings are mandatory — every report ends with the checked-and-clean list (e.g. "no hardcoded secrets; CI permissions sound")
- Context-grounded severity — CRITICAL/HIGH require a concrete harm path in THIS codebase's real context; importing generic-checklist requirements (web-scale demands on an internal desktop tool) is itself a critique target
- Proportionate fixes — an over-engineered fix (a DI container for one seam) is a critique target even when the finding stands
- No subagents — reviewers do all reading and analysis themselves, in their own context; they never delegate to background agents
- Read-only — reviewers modify nothing and return the report as their final message
Recovery procedures
| Symptom | Action |
|---|---|
| Reviewer delegated to its own background agent and stalled | SendMessage the reviewer: "Do not delegate. Do the review yourself in this context, now." |
| Reviewer died mid-run (e.g. API Overloaded) | SendMessage-resume the same agent — the transcript survives and work is not lost. Do not respawn fresh; that loses its Phase 1 context. |
| Malformed or incomplete report | One SendMessage re-ask against the output contract |
Common mistakes
- Verifying fixes in the authoring context — in the proving run, a ratio-inversion error inside a fix text ("2/5" vs "3/5" lock sites) was caught only by the fresh round-2 reviewer
- Dropping the design/maintainability lens — orchestrators left to themselves converge on correctness-vs-security and produce no maintainability findings
- Treating cross-critique as consensus-seeking — "plausible but unverified" is not SUPPORT
- Silently dropping rejected findings — keep them in the report with the reason, so the same false alarm is not re-raised later
- Skipping Phase R because "the fixes were straightforward"
Evaluation record (ADR-0027 risk-adaptive lane)
Before using a report as Adversarial-Lane: fired, verify its currentness with
the read-only CLI (Node and mcp/sdd-forge-mcp dependencies must be installed):
node mcp/sdd-forge-mcp/scripts/check-adversarial-report.mjs --repo . --report /ABSOLUTE/EVIDENCE-CHECKOUT/reports/adversarial-review/BRANCH/report.md --base origin/main --report-sha256 SAVED_REPORT_SHA256
At review completion, record the SHA-256 of the final report bytes separately
in the review receipt or PR metadata as report_sha256. Pass that saved digest
above; do not recompute it from the current report to make verification pass.
The digest is external to avoid a self-referential hash inside the report.
Record diff_sha256 from the bytes of
git diff --binary --no-ext-diff --no-textconv MERGE_BASE_SHA..HEAD_SHA.
Exit 0 and status: current are required; nonzero (including unavailable Git,
missing files or invalid metadata) cannot satisfy the lane. This command does
not launch agents, change review verdicts, or modify repository files. The same
command and JSON output apply in Bash and PowerShell.
Publish evidence without moving the reviewed HEAD
Keep the final report and its companion files outside the reviewed branch.
The reports/adversarial-review/<branch-slug>/ path is relative to a separate
evidence checkout, not a requirement to commit evidence on the target branch.
Use a separate evidence repository or a separate evidence branch/worktree that
will not be merged into the target before its currentness check.
- Finish and commit the target changes; record that exact HEAD, merge base, and full diff digest for the review. Do not modify them to fit a report.
- Produce the report and any
evaluation.json/cross-critique annex under the canonical path in the evidence checkout. Save the final report digest in a separate receipt before publication. - Commit/publish the evidence there. In the target PR, link to the report at the immutable evidence commit, and record the target HEAD, merge base, and saved report digest. Do not use a mutable evidence-branch URL.
- To verify, retrieve that evidence commit, then pass its absolute report
path to
--reportand the reviewed checkout to--repo, as above. Verify against the target PR's current HEAD and base; do not check out an old target commit merely to obtain a passing result.
Committing a report or receipt on the target branch changes HEAD and makes the old report stale, even if no product code changed. There is no evidence-only commit exemption. Historical reports may remain in the target repository but cannot claim currentness. A target update requires a fresh review of the new target, not editing the old report's hashes. Publishing evidence separately avoids a circular report/commit hash without excluding any target diff files.
When invoked as the ADR-0027 pre-PR lane (i.e. the firing predicate is
satisfied), the orchestrator produces an evaluation.json alongside report.md
in the evidence checkout's reports/adversarial-review/<branch-slug>/.
Non-triggering invocations
produce no evaluation.json.
evaluation.json must conform to
contracts/adversarial-review-evaluation.v1.schema.json. Fill all required
fields at the end of Phase 3 (synthesis). Update phase_r.* after Phase R
completes.
Every new evaluation must include token_usage. Use a measured total_tokens
and its telemetry source only when the host reports usage for the complete
review run (including resumed/recovery calls). Otherwise record total_tokens: null and a nonblank unavailable_reason, including partial telemetry as an
unavailability reason. Never estimate tokens or substitute zero. This is an
observability record, not a gate failure or a verdict input. Older v1 records
without this field remain readable; do not retrofit guessed values into them.
Use full 40-character commit IDs. Compute the target digest without external diff drivers so the identity is reproducible across hosts:
git diff --binary --no-ext-diff --no-textconv "$merge_base_sha".."$head_sha" | sha256sum
Minimum required fields at synthesis time:
{
"schema_version": "adversarial-review-evaluation.v1",
"branch_slug": "<branch-slug>",
"created_at": "<ISO-8601 UTC>",
"report_path": "reports/adversarial-review/<branch-slug>/report.md",
"trigger_reasons": ["workflow_surface"],
"reviewer_launch_count": 2,
"token_usage": { "total_tokens": null, "unavailable_reason": "host does not expose complete run token telemetry" },
"continuation_status": { "reviewer_a": "resumed", "reviewer_b": "resumed" },
"finding_counts": { "phase1_total": 0, "cross_critique_new": 0 },
"basis_counts": { "code_evidence": 0, "spec_evidence": 0, "concern": 0 },
"scope_counts": { "in_scope": 0, "out_of_scope": 0, "unclear": 0 },
"phase_r": { "ran": false, "not_ran_reason": "fixes not yet landed" }
}
Update phase_r to "ran": true with counts when Phase R completes.
Contracts and schemas
Set the annex's root review_lane to standalone-adversarial; severity-change
proposals use exactly CRITICAL|HIGH|MEDIUM|LOW. Do not convert these to the
SDD gate vocabulary or rewrite the original reviewer verdicts. An absent lane
retains legacy SDD gate semantics (Critical|Major|Minor).
For a completed annex with verdicts: [], record source_finding_count: 0
only after reading both original blind-review outputs and confirming they
contain no findings. Missing or unavailable outputs are not zero findings;
record the annex as unavailable with its reason instead. A nonempty source
review cannot become a completed empty annex by dropping its critiques. The
count is an explicit declaration, not independent verification of those
outputs; retain the original reports for review. Nonempty historical annexes
remain readable without this field.
Before using a cross-critique annex as evidence, run the read-only checker against the final JSON file (the same command works in Bash and PowerShell):
node mcp/sdd-forge-mcp/scripts/check-cross-critique.mjs /ABSOLUTE/EVIDENCE-CHECKOUT/reports/adversarial-review/BRANCH/cross-critique.json
Exit 0 with status: valid proves contract conformance and ordered citation
ranges, not the truth of a claim. Every evidence citation requires a nonblank
path and claim plus positive line_start and line_end; a single-line citation
uses equal coordinates. The checker rejects line_end < line_start, which
plain Draft-07 validation alone cannot enforce. Fix invalid annexes before
using their proposals; do not rewrite persisted reviewer verdicts or treat a
failed/unavailable checker as successful validation. Required Node dependencies
are the same as for the report-currentness checker above.
| Schema | Purpose |
|---|---|
contracts/cross-critique.v1.schema.json |
cross-critique.json annex (issues #347, #348) |
contracts/adversarial-review-report.v1.schema.json |
Report metadata block (issue #349) |
contracts/adversarial-review-evaluation.v1.schema.json |
evaluation.json run metrics (issue #350) |
Real-world impact
Proving run (torque-system-manager, 2026-07-07, PR #7): cross-critique and fresh verification found a target service with zero production call sites (requirement re-scoped), two HIGH defects in TDD-complete code (unguarded DisposeAsync on the close path; a swap-then-dispose ordering bug), a wrong lock-site count inside a fix text, and re-calibrated four of five initial High/Medium severities — offsetting single-review severity inflation. External benchmark (2026): adversarial panels find roughly 20% more bugs than a single review.
Usage history: reports/adversarial-review/
04 同仓库更多 Skills
status
Show a read-only Jira-style six-view SDD dashboard in the initiating parent's Sites or Claude Artifacts, with source freshness and failure visibility.
verify-review-reservation
Recheck the bounded identity-ledger reservation invariant after lock, hash-check or publication changes.
aws-cdk
Authors, deploys, and troubleshoots AWS infrastructure using CDK with TypeScript or Python. Covers best practices, stack architecture, and construct patterns. Applies when writing CDK constructs, bootstrapping environments, running cdk deploy/synth/diff, fixing CDK or CloudFormation errors, planning stack structure, importing existing resources, resolving drift, or refactoring stacks without resource replacement.
quality-gate
Independently verify an Implementation Complete task with a Default-FAIL verification contract, deterministic checks, and an isolated critical reviewer, then decide whether it is Done.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.
ship
Implement approved SDD tasks through the quality gate to Done — the second of the two-command workflow. Run after /sdd-bootstrap:bootstrap and human task approval.