adversarial-review

Files (25)

• SKILL.md
• acceptance.feature
• expected.md · self-test/01-draft-signal-no-oracle/
• manifest.json · self-test/01-draft-signal-no-oracle/
• expected.md · self-test/02-sound-gate-with-oracle/
• manifest.json · self-test/02-sound-gate-with-oracle/
• expected.md · self-test/03-never-sound-gate-without-oracle/
• manifest.json · self-test/03-never-sound-gate-without-oracle/
• expected.md · self-test/04-independent-dispatch/
• manifest.json · self-test/04-independent-dispatch/
• expected.md · self-test/05-cannot-assess-empty-praise/
• manifest.json · self-test/05-cannot-assess-empty-praise/
• expected.md · self-test/06-advisory-never-self-adjudicate/
• manifest.json · self-test/06-advisory-never-self-adjudicate/
• expected.md · self-test/07-clean-pass-no-manufactured-findings/
• manifest.json · self-test/07-clean-pass-no-manufactured-findings/
• expected.md · self-test/08-clean-sound-gate-green-oracle/
• manifest.json · self-test/08-clean-sound-gate-green-oracle/
• expected.md · self-test/09-verifier-refutes-false-positive/
• manifest.json · self-test/09-verifier-refutes-false-positive/
• expected.md · self-test/10-verifier-confirms-real-finding/
• manifest.json · self-test/10-verifier-confirms-real-finding/
• expected.md · self-test/11-uncertain-refute-reaches-the-human/
• manifest.json · self-test/11-uncertain-refute-reaches-the-human/
• README.md · self-test/

SKILL.md (first lines)

# Adversarial Review

Drive an independent adversarial critic at a completed task. Frame the target, dispatch a reviewer that
never sees the builder's reasoning, put each finding to an independent judge, and present what survives
to the human. Judge nothing yourself and decide nothing about "done": the judgment belongs to the
reviewer and the judge, the decision to the human.

The standards a review is held to are whatever applies to the target —
`${CLAUDE_PLUGIN_ROOT}/rules/coding.md`, `${CLAUDE_PLUGIN_ROOT}/rules/testing.md`,
`${CLAUDE_PLUGIN_ROOT}/rules/architecture.md`, `${CLAUDE_PLUGIN_ROOT}/rules/writing.md`, and the target's
own stated intent. **Where the target adds or changes tests, add
`${CLAUDE_PLUGIN_ROOT}/rules/test-patterns.md`** — a suite that is green because its tests assert on
mocks of in-process collaborators, or compute their expected values, proves less than its colour, and
that gap is evidence against "done".

Three roles keep the concerns apart. The **builder** is whoever did the work — the main session or a
delegated AI. The **adversary**, `agents/adversarial-reviewer`, attacks and raises findings. The
**judge**, `agents/adversarial-verifier`, confirms or refutes each finding without seeing the adversary's
reasoning, so a motivated attacker cannot rubber-stamp its own findings. The reviewer agent is the
reusable unit and its typed verdict is the composition contract (see *Composition contract*); this skill
is only the standalone human driver.

---

## Invariants

1. **Independence (C1).** Dispatch the reviewer in **fresh context** with the target, intent, standards
   and any `oracle_result` **only**. Withhold the **builder's reasoning and self-assessment**: a reviewer
   that sees them agrees with the builder instead of judging the work. The judge is independent of the
   reviewer in the same way.
2. **Advisory, never self-adjudicating (C3).** The reviewer emits findings and the judge confirms or
   refutes them; neither declares the task done or not done. **The human decides.** Present; never
   rule.
3. **Honesty label (C4).** The label is **mechanical**: `sound-gate` iff a deterministic oracle backed
   the review, else `draft-signal`. It answers "did an oracle back this?", never "how sure is the
   reviewer?", and verification never changes it. Present a soft review as a draft signal and a real
   oracle result as a sound gate — over-claiming and under-claiming both fail. Never invent or approximate
   an oracle to earn the label.
4. **Adversary and judge stay separate.** The reviewer raises findings and a separate judge confirms or
   refutes each. Present only judge-confirmed findings as confirmed.
5. **No manufactured findings, no empty praise (C5).** A clean pass is honest; praise with no span is
   coerced to `cannot-assess` — the reviewer owns this; never override it toward approval.
6. **Edit or fix nothing.** This skill reviews; it does not change the work.
7. **Report the verdict as it is.** Soften no major finding and invent none.

---

## Parse the argument

| Pattern | Action |
|---|---|
| `"<target>"` — an explicit path or artifact name | Review that named target. |
| `--intent "<...>"` | Use this as the stated intent, the claim-of-done; otherwise infer it. |
| No argument, or a bare "the task I just completed" | Review the task just completed in this session; infer the target and intent from the conversation leading up to the invocation. |

A composing host passes the intent explicitly; standalone, infer it from context. Inferring the
**intent** is fine; inferring or importing the **builder's reasoning** breaks invariant 1.

---

## FRAME — establish the review contract

Assemble three things, and only these:

1. **Target** — the completed artifact or artifacts under review. With no argument, identify what was
   just completed from the conversation. If that is ambiguous, ask the developer what to review — one
   short question — rather than guessing.

   **That ask follows `${CLAUDE_PLUGIN_ROOT}/skills/shared/decision-request.md`.** Load it before the call.
   The candidate scopes go in the context block — this skill is the only thing that knows what they
   are — and the counted ask says what turns on the choice: a wrong scope reviews work nobody asked
   about and misses the work that was done.
2. **Intent** — the claim-of-done: what the task was meant to achieve, stated by the host, given via
   `--intent`, or inferred from context. Show an inferred intent to the developer so they can correct
   it.
3. **Standards** — the rules above that fit the target type: code → `coding.md`, `testing.md` and
   `architecture.md`, plus `test-patterns.md` when tests change; prose → `writing.md` and any rule the
   prose is about; a skill or agent → `writing.md` and the conventions of the plugin it belongs to.

Begin the review only once the target and intent are settled.

---

## ORACLE — run or inherit a deterministic check (sets the label)

Run the oracle here, in the driver: the reviewer stays read-only and only *cites* the result. Inherit a
result a host already captured; never re-implement it.

- **Code target:** detect a test runner via `${CLAUDE_PLUGIN_ROOT}/skills/shared/test-runner-detection.md`;
  if one exists, run the suite, and lint and types if present, and capture the result.
- **Prose target** (skill, agent, rule, doc): run the deterministic checks that apply — a scripted
  self-test fixture run, a dead-link or skill-ref scan, a frontmatter, length or citation check — with
  the repository's own scripts or a standard tool such as a YAML parser. Capture each result. A fixture
  suite a model drives is not one, and neither is a check improvised to stand in for judgment: neither
  earns `sound-gate`.
- **No deterministic oracle** (a design doc's "soundness", a subjective artifact): proceed with no
  `oracle_result`.

Record the outcome as `oracle_result` — the captured output and what was run — or note that none was
available. **An oracle ran → `sound-gate`; none → `draft-signal`.** If the only "check" is your own
judgment, there is no oracle.

---

## CURATE — assemble independent input (invariant 1, the load-bearing step)

Build the reviewer's input as **exactly** `{ target, intent, standards, oracle_result? }`, with
`oracle_result` omitted when none ran. Strip everything else: builder reasoning, self-assessment, a
prior "looks good to me", your own opinion of the work. An `oracle_result` is a machine-produced fact
and must pass; a builder's *claim* that "the tests pass" is not one — pass the captured result, never
the claim.

Independence has two parts, and they are not equally strong. The **fresh-context dispatch** is
structural: the subagent cannot see this session. The **curation** is a discipline you apply inside a
builder-adjacent context, and nothing mechanical stops the builder's rationale reaching the contract —
fixture 04 guards it as a regression check, not a boundary. When in doubt, pass less. The same actor
curating is an accepted limitation; a different-model or multi-lens reviewer is the seam left for
hardening it.

From pmvanev/phil-claude-plugin, MIT.

More from pmvanev/phil-claude-plugin