pm-skills/pm-ai-shipping/skills/code-review/SKILL.md

---
name: code-review
description: "Review code for actionable defects. Correctness is the core; performance and security are optional sub-cases of the same engine. Anchors on agreements between participants across a boundary, forces a violating execution, and refutes every candidate before reporting. Use when asked to review changes, find bugs, audit a codebase, or check whether a fix is safe."
---

# Code Review

## Purpose

Most review output is noise: a list of things that *look* wrong, unranked, unrefuted, and impossible
to act on. This skill produces the opposite — a small number of findings, each with a required
behaviour, a feasible trigger, a concrete contradiction, an observable consequence, and the strongest
counterargument already checked.

Its central bet: **the defects reviewers miss are rarely visible inside one file.** They are
disagreements between two participants that each look reasonable alone — a caller and a callee, a
producer and a consumer, a writer and a later reader, two branches that should establish the same
state. A checklist applied file-by-file cannot see those, because the two halves are never in view at
the same time. So the unit of review here is the **agreement**, not the file.

## Structure: one engine, three anchors

Code review is the skill. **Correctness is its core** — the dimension generic tooling covers worst,
and the one described in full below. **Performance and security are sub-cases**: the same engine, the
same refutation discipline, the same report contract, with a different anchor and one or two extra
rules each.

| Sub-case | Anchor | Where its rules live |
|---|---|---|
| **Correctness** *(core, default)* | Agreements between participants across a boundary | This file + `references/correctness-taxonomy.md` |
| **Performance** | Workload → resource demand → growth or contention → consequence | `references/performance-review.md` |
| **Security** | Source → trust boundary → sink, with an attacker controlling the source | `references/security-review.md` |

Read a sub-case's file only when that sub-case is selected. Each is short on purpose: it states what
*differs*, and the rest of this file still applies.

Sub-cases are independently *activated*, not mutually exclusive. One root cause can carry correctness
and security impact — report it once, with both impacts.

## Invocation

```
/pm-ai-shipping:code-review
/pm-ai-shipping:code-review dimensions=correctness scope=changes
/pm-ai-shipping:code-review dimensions=performance,security
/pm-ai-shipping:code-review dimensions=all
```

Claude Code ships its own bundled `/code-review`. Use the plugin-qualified form above when you mean
this one.

These are instruction arguments, not shell flags.

- **Default: `correctness`.** Bare "review this" or "find bugs" means correctness only.
- An explicit list selects exactly those sub-cases; `all` selects three. Never silently reinterpret
  an unknown or empty selection — ask.
- **Scope:** use what was asked. Otherwise review working changes if present, else the repository.
- **State the selected dimensions, the scope and the comparison baseline before investigating.**
- Reviewing changes means following dependencies *beyond* the changed lines, and distinguishing
  defects the change **introduced** from defects it merely **revealed**.
- Review and report. Apply fixes only when asked.

## Shared engine

Every sub-case uses one skeleton. Only the anchor and the refutation rules differ.

**Map a flow → identify an obligation → inspect every participant → construct a violating execution
→ trace the consequence → attempt refutation → report.**

Build one minimal map first: inputs, major execution flows, who owns which state, external
dependencies, observable effects. Each selected sub-case enriches it — do not build three maps, and
do not make a security-only run wait on correctness mapping.

## Correctness: the agreement engine

A *boundary* is semantic, not a file split. It separates a caller and a callee, two callbacks, two
executions of the same function, a producer and a consumer, or a value written now and read later.

For each consequential agreement, hold these in working notes — not in the report:

```
Participants:
Value, entity or effect exchanged:
Authority (who decides the real answer):
Identity and lifetime/version:
Required relationship:
Evidence for that relationship:
Relevant transitions or orderings:
Observable consumer or consequence:
```

**Establish the obligation without inventing intent.** Evidence comes from specifications,
documented contracts, language or protocol semantics, tests that encode an expectation, or a
necessary producer/consumer relationship. A consumer's implementation alone does not prove the
consumer is right. Where participants disagree, say why the disagreement produces a *wrong outcome* —
sometimes the contradiction is certain while which side should change is genuinely open. Missing
documentation is a limitation, not automatically a finding.

**Start where agreements are most likely to break:** values transformed or negotiated, identities
reassigned, work becoming asynchronous, state persisted and reloaded, several effects that must
agree. Then do a local pass over ordinary decisions, arithmetic, boundaries and error branches — the
anchor must not become a filter that discards plain bugs.

### Force a violating execution

A suspicion is not a finding until you construct the execution that breaks it. Where the
implementation permits:

- make a **requested** value differ from the **accepted or effective** one;
- keep two operations live at once and vary their completion order;
- change the relevant identity or generation between observation and use;
- compare distinct transitions that should end in equivalent state;
- inject failure between effects, and interruption before completion;
- exercise empty, exact-boundary and adjacent-boundary inputs.

Establish that each case is actually reachable. Do not assume it.

### Two lenses that need a forced probe, not a mention

Across a large evaluation of planted runtime defects in real codebases, two classes were almost never
*even reported* by strong agents — not missed at the fix, missed at the look. Naming them in a
checklist will not help; each needs an explicit probe:

1. **Authority reconciliation.** Follow a proposed value through validation, normalisation,
   negotiation or commit, and find downstream state still derived from the **proposal** where the
   authority can return something different. *A requested value is not an applied value.* Probe:
   force them apart and ask what still reads the request.
2. **Identity and correlation.** Trace how an operation's result finds its originating entity, then
   establish that the key is unique, stable and live for long enough — under overlap, reordering,
   removal and reuse. A label, a position or arrival order is suspicious exactly when those
   properties can fail. Probe: run two operations concurrently and complete them out of order.

The full set of thirteen diagnostic lenses, each with a detection tell, is in
`references/correctness-taxonomy.md`. They are overlapping lenses, not a quota to fill.

## Refutation: the discipline that makes this worth running

A candidate becomes a finding only with all five:

1. **A supported obligation** — what must hold, and on what evidence.
2. **A feasible execution** — inputs, state and ordering the real system permits.
3. **A concrete contradiction** — where the obligation fails.
4. **An observable consequence** — wrong output, state, effect, completion or progress.
5. **An examined counterargument** — the strongest mechanism that would prevent or repair it.

Actively hunt for the refutation: an enclosing guarantee that makes the execution impossible;
synchronisation excluding the interleaving; reconciliation before any consequential read; an
intentional contract; a precondition excluding the input; a different owner responsible for it.

| Outcome | Rule |
|---|---|
| **Keep** | Evidence establishes the defect; the counterargument checked does not prevent it. |
| **Drop** | Cited evidence defeats the execution, the obligation or the consequence. |
| **Unresolved** | An essential contract or runtime fact is unknown. List it *separately from findings*. |

Do not import the security sub-case's attacker/victim test into correctness. **A correctness defect
can harm only the person who triggered it and still be serious.** Equally, "keep unless disproved" is
too permissive here — an ungrounded suspicion with no constructed execution is not a finding. When
both sub-cases are active, apply each test only to its own dimension.

**Absorption is not prevention.** The most expensive refutation mistake is finding something
downstream that happens to hide the defect - a cache that usually holds the value, a retry that
usually succeeds, a default that is usually right - and dropping the finding. That is not a
guarantee, it is a coincidence with good odds, and it fails the day the absorber is cold, evicted or
reconfigured. Drop only on a mechanism that makes the execution *impossible*, and say which mechanism
it was. For the same reason, **"it works nearly always" describes a race, not a refutation** - a
timing window that usually resolves correctly is a finding, and the fact that you had to reason about
which side usually wins is the evidence.

Passing tests, unfamiliar code, a suspicious name, a missing test and a sibling difference are
evidence to investigate — none of them is proof, and none is refutation. Deduplicate by violated
agreement and root cause, never by file. There is no findings quota; zero supported findings is a
valid result.

## Parallelism

Fan out over **complete flows or connected groups of agreements** — never over files, and never one
agent per taxonomy class. Partitioning by file is precisely the split that hides cross-boundary
defects, which are the ones worth finding.

1. The coordinator builds the initial map and identifies shared state.
2. Each worker gets a bounded flow, its participants, the selected sub-cases and open questions.
3. Workers inspect **both sides** of their agreements and may follow dependencies outside their list.
4. Workers return candidates, cited evidence, completed refutations and unresolved relationships.
5. The coordinator reconciles assumptions and any relationship that crosses assignments.
6. Strong candidates get a separate verification pass before they are reported.

**Allow overlapping reads.** Two workers reading the same authority is far cheaper than either one
holding half its contract. Keep integration capacity in reserve: an unresolved relationship spanning
two assignments stays unexamined until someone closes it. One level of fan-out is the target; if
delegation is unavailable or the scope is small, run the same procedure sequentially.

**Run workers on the strongest model available, and match the current session's effort level.** This
is recall-first work: a missed cross-boundary flow is the costly failure, and a worker that silently
drops to a cheaper model or a lower effort is the cheapest way to lose one. If any worker is rerouted
or downgraded, say which in the report — a reader who assumes one model saw everything will
misjudge the coverage.

**One model, unless told otherwise.** Fan-out here is for coverage, not for a second opinion: every
worker runs the same model as the coordinator. Do not bring in a second model to cross-check findings
unless explicitly asked. Mixing models makes the result unattributable — when this skill is being
measured, or compared across models, a single foreign worker invalidates the number. The independent
second-model pass is a separate, explicitly-invoked step (`/ship-check` Step 6), never something this
skill reaches for on its own.

**Give workers read-only tools.** A review worker needs to read, search and navigate — nothing more.
Withhold file writes, edits and any mutating command; allow read, search and non-mutating inspection.
Three reasons, in order of importance: a worker that can edit will drift from reviewing into
"helpfully" fixing and stop reporting what it silently repaired; the repository under review must end
the run byte-identical to how it started, or the findings cannot be checked against it; and a
read-only worker cannot damage a working tree it misunderstood. If the host cannot restrict tools,
say so in the prompt and verify the tree is unchanged when the run ends.

## Report

Lead with supported findings, ordered by impact. Keep severity separate from evidential strength.

```
Review scope:
Comparison baseline:
Selected dimensions:

[Severity] [Dimension] Concrete consequence
  Expectation:  required behaviour, and the evidence for it
  Trigger:      feasible preconditions and execution
  Defect:       the violated relationship
  Evidence:     source locations for EVERY participant
  Impact:       observable consequence and affected scope
  Refutation:   strongest counterargument checked, and why it fails
  Remedy:       minimal correction to the violated relationship
  Verification: what was executed, versus established from source

Coverage:
Unexamined areas and essential unknowns:
```

Cite **both** participants for a cross-boundary defect, and do not group findings only by file — that
hides the relationship the review exists to find.

**Coverage means work performed, not boxes ticked.** For each selected sub-case report: examined with
supported findings · examined, none supported · not applicable, with reason · not examined, with
reason. Zero findings in a category does **not** mean "not covered", and a table of ticks is not
evidence of completeness. Say "no supported findings in the examined scope" — never that the code is
bug-free.

## Notes

- Say explicitly what is well built. A review that only accuses is easy to dismiss.
- The two sub-cases have mature commands behind them: `/security-audit-static` (trust boundaries,
  sinks, OWASP backstop) and `/performance-audit-static` (over-fetching, indexes, caching). Run the
  command when the sub-case is the whole job; use the reference file when it is one dimension of a
  broader review. This skill does not restate either.
- For the doc-vs-code axis use the `intended-vs-implemented` skill.
- A static review produces code-review findings, not confirmed exploits or measured regressions.