voyage/skills/reviewing-adversarially/SKILL.md

---
name: reviewing-adversarially
description: "The stance of a reviewer who judges someone else's work. No praise, no finding without a source (file:line or a quoted line), no downgrade without a reason, an honest account of what was read in full and what only as a summary, a Declined to Judge list so nothing set aside disappears, every claim of done or green checked against the diff and the output rather than the report, and the review axes kept separate. Use when judging a diff, an implementation plan, a task brief or a helper's report before it is merged, approved or acted on, when deciding whether delivered work matches what was promised, or when an author asks for a quick approval."
---

# Reviewing adversarially

## Overview

How a reviewer in Voyage judges. It holds for every agent whose job is a
verdict on someone else's work: the two `/trekreview` reviewers and their
coordinator, `scope-guardian`, `plan-critic` and `brief-reviewer`. The agent's
own role (its dimensions, its finding schema, its verdict rule) stays in the
agent; this skill is what all of them share.

Being useful to the author is not the same as agreeing with the author. A
review the author enjoys reading but that lets a defect through has failed.

## When to use

- A diff, a plan, a brief or a helper's report is judged before it is merged,
  approved or acted on.
- Someone asks whether delivered work matches what was promised, or whether a
  step is done.
- The author asks for a quick thumbs-up, says "looks good, right?", or says a
  problem is cosmetic.
- Not for: improving the wording or style of a text (that is editing, not a
  verdict), or running Claude Code's own `/code-review` engine, which brings
  its own method.

## Process

### 1. No praise

- Write no sentence whose job is to commend the work or the author: "clean",
  "tidy", "nice", "readable", "solid", "well done", "looks good". A part
  with no finding gets no sentence; silence is the verdict.
- Do not open with agreement ("Absolutely", "Great point", "You're right").
  Do not restate the author's claim in stronger words than they used, and do
  not add enthusiasm they did not express.
- "Right?" and "don't you think?" are questions to evaluate, not cues to
  confirm. Before you endorse anything, look for at least one real risk; if
  there is none, say what you checked.
- Measured: without this skill, 2 of 6 review runs praised the code ("tidy",
  "small and readable"), both where the author asked "looks good, right?".

### 2. No finding without a source

- Every finding points at its evidence: **`file:line`** in the file as it
  stands after the change (not the line in the diff), or a **verbatim quote**
  of the plan, brief or report line it concerns.
- A function name, a file name alone or "the date handling" is not a source.
  If you cannot point, the finding is either dropped or moved to Declined to
  Judge (step 6) with what would settle it.
- A finding about deleted code cites the old line as `<rev>:<path>:<line>`.
- Measured: without this skill, 6 of 6 runs raised at least one finding with
  neither a line nor a quote (8 findings in all).

### 3. A claim is checked against evidence

A report is a claim. You judge the work, not the report.

| Claim | Requires | Not sufficient |
|---|---|---|
| "Step done" / "helper finished" | the diff shows the change | the helper's report |
| "Tests pass" | output you saw: 0 failed, and the tests that matter not skipped | "npm test is green" in a report |
| "Test added for X" | the test, in the diff, asserting X | a test file that exists |
| "Requirement met" | each requirement traced to a line | the suite passing |
| "Bug fixed" | the original symptom, now checked | code changed near it |

"The helper said done" requires the diff, not the report. When a reviewer
cannot run anything, it says that the run was not seen and judges from the
code alone.

### 4. Say what you read, and how

- State what you read in full, and what you saw only as a summary, a
  signature list or a line count.
- A file seen as summary only gets **no verdict**: it is "not reviewed",
  never "probably fine". Summary-only coverage covers declared signatures,
  nothing more.
- Do not judge what you did not measure. "Probably fine", "looks correct",
  "believable", "should be fast enough" are verdicts with no evidence: cite
  the evidence, or move the item to Declined to Judge.
- Measured: without this skill, 4 of 6 runs judged something they had not
  measured ("probably fine because the code is linear", "look correct as
  written", "npm test is green is believable").

### 5. No downgrade without a reason

- Severity comes from the agent's own scale (the rule catalogue for
  `/trekreview`, the plan review's tiers for the plan critics). An author, a
  lead or a deadline calling something "a nit" or "cosmetic" is not a reason.
- When a rule lets you lower a finding, name the rule and what catches the
  defect instead (`lowered_from`, `caught_by`). With no named rule, keep the
  tier or drop the finding as wrong; never soften it in between.

### 6. Declined to Judge: nothing disappears silently

Before the verdict, write a separate list headed **`## Declined to Judge`**
(in `review.md` it is the required section of that name; in other outputs,
a section with that title before the verdict and the JSON block). One line
per item you considered and did not rule on:

```
src/receipt.mjs - summary only in the bundle - needs the full diff
plan "handles 10 000 plants in under 50 ms" - no benchmark in the change - needs a timed run
```

An item that is also a finding (a file nobody could review) is listed here
too. An empty list is written `None.`, which says you set nothing aside.
Measured: without this skill, 0 of 6 runs had such a list; the set-aside
items were mixed into the findings at made-up severities.

### 7. The axes stay separate

- Brief conformance, code correctness, scope, security and design are
  different axes. Report each on its own; do not merge them into one score
  or rerank findings across them.
- Name the worst issue within each axis, never a single winner across axes.
- The verdict comes from the agent's own rule (a threshold table, a gate),
  not from an overall impression.

## Red flags

| Thought | What it means |
|---|---|
| "The rest is clean, I'll say so to be fair" | That sentence is praise. A part with no finding gets no sentence (step 1). |
| "They asked 'right?', a short yes will do" | It is a question. Evaluate, then answer with findings or with what you checked (step 1). |
| "Everyone can see which function I mean" | Then cite its line. A name is not a source (step 2). |
| "The report says the tests pass" | A report is a claim. What did the diff and the output show (step 3)? |
| "I only saw a summary, but it's probably fine" | Summary only means not reviewed. Put it under Declined to Judge (steps 4 and 6). |
| "The lead says it's cosmetic" | Not a reason. Keep the tier, or name the rule that lowers it (step 5). |
| "I'll leave out what I couldn't check; it would only clutter the review" | Leaving it out is how it disappears. List it (step 6). |
| "The style issue is the most visible, I'll lead with it" | Axes stay separate; the worst issue is named per axis (step 7). |

## Enforced by

- `lib/review/findings-schema.mjs` rejects a `/trekreview` reviewer finding
  with no `file`, a non-integer `line`, or a line past the end of the file,
  and `/trekreview` re-asks the reviewer. It is **partial**: a file-level
  finding with line 0 passes, and nothing checks that the cited line
  supports the claim.
- `lib/review/coordinator-contract.mjs` drops a finding with no citation
  (`no-citation`) in the deterministic mirror of the coordinator. Partial in
  the same way, and it covers `/trekreview` only, not the plan critics.
- `lib/validators/review-validator.mjs` fails a `review.md` (review_version
  1.1 or later) without a `## Declined to Judge` section. It checks that the
  section exists, not what it lists.
- Praise and flattery are **prose only**: no check reads the reviewer's
  prose for them. So are downgrades without a reason, the account of what was
  read and how, a Declined to Judge list in any output other than
  `review.md`, claims checked against evidence, and the separate axes.

## Credits

Ideas adapted, text rewritten; no code or prose copied.

- obra/superpowers @8ca22db, `skills/requesting-code-review/code-reviewer.md:33-48`: the
  "declined to judge" list before the verdict, so nothing set aside is dropped silently; and
  `skills/verification-before-completion/SKILL.md:38-48`: the claim / requires / not sufficient
  table, including "agent completed" requiring the diff, not the agent's report. MIT, Copyright (c)
  2025 Jesse Vincent.
- mattpocock/skills @c55ee46, `skills/engineering/code-review/SKILL.md:76-78`: two review axes
  are reported separately and never reranked into one winner. MIT, Copyright (c) 2026 Matt Pocock.
- The measured lines come from Voyage's own baseline review runs without this skill; see
  `docs/skills-authoring.md`. Step 1 keeps the substance of the earlier per-agent
  "Interaction Awareness" block, which this skill replaces.