code-review · diff

git:20261102.f98f184 to git:20261108.696d3dd

59 added, 138 removed. Audit A to A.

What this update changes in the checks

No check changed: every fixed check gives the same answer before and after this update.

A tripped check is a label, not a verdict: read the matched text and the lines below. This week's updates that newly trip a check.

---
name: code-review
description: "'Review this', 'find bugs', 'is this fix safe': review code for defects that matter, correctness first, each finding refuted before it's reported."
---
# 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.
+ **Review for supported defects with concrete consequences and checked counterarguments.** Most review output is noise: unranked suspicions that cannot be acted on. Each finding here needs required behaviour, a feasible trigger, a concrete contradiction, an observable consequence and the strongest counterargument 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.
+ **the defects reviewers miss are rarely visible inside one file.** They are disagreements between participants that each look reasonable alone. Examples include caller and callee, producer and consumer, writer and later reader, or branches that should establish the same state. A file-by-file checklist never holds both halves together. Review 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.
+ **Use correctness as the core, with performance and security as sub-cases.** Generic tooling covers correctness worst. Each sub-case uses the same engine, refutation discipline and report contract. Only its anchor and one or two extra rules differ.
| 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.
+ | 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` |
- Sub-cases are independently *activated*, not mutually exclusive. One root cause can carry correctness
- and security impact — report it once, with both impacts.
+ **Read a sub-case's file only when that sub-case is selected.** Its short file states what differs; the rest of this file still applies. Sub-cases activate independently, not exclusively. Report one root cause once, with both impacts when it carries correctness and security impact.
## Invocation
+ **State the selected dimensions, the scope and the comparison baseline before investigating.** These are instruction arguments, not shell flags:
+
```
/ai-shipping:code-review
/ai-shipping:code-review dimensions=correctness scope=changes
/ai-shipping:code-review dimensions=performance,security
/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.
+ Claude Code ships its own bundled `/code-review`. Use the plugin-qualified form above when you mean this one.
- - **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**.
+ - 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.
+ - Use the scope asked for. Otherwise review working changes if present, else the repository.
+ - When reviewing changes, follow dependencies beyond changed lines. Distinguish 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 the flow, establish an obligation and try to refute its violation.** Every sub-case uses this sequence; only its anchor and refutation rules differ:
- **Map a flow → identify an obligation → inspect every participant → construct a violating execution
- → trace the consequence → attempt refutation → report.**
+ 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.
+ Build one minimal map first: inputs, major execution flows, state owners, external dependencies and observable effects. Enrich it for each selected sub-case. Do not build three maps or 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.
+ **Track consequential agreements across semantic boundaries, not just file splits.** A boundary separates caller and callee, callbacks, executions of one function, producer and consumer, or a value written now and read later.
- For each consequential agreement, hold these in working notes — not in the report:
+ For each consequential agreement, hold these in working notes, not 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.
+ **Establish the obligation without inventing intent.** Use specifications, documented contracts, language or protocol semantics, tests encoding expectations, or a necessary producer/consumer relationship. A consumer's implementation alone does not prove the consumer is right. When participants disagree, explain why the outcome is wrong. The contradiction may be certain while which side should change remains 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.
+ **Start where agreements are most likely to break.** Inspect transformed or negotiated values, reassigned identities, asynchronous work, persisted and reloaded state, and several effects that must agree. Then inspect ordinary local decisions, arithmetic, boundaries and error branches. The anchor must not discard plain bugs.
### Force a violating execution
- A suspicion is not a finding until you construct the execution that breaks it. Where the
- implementation permits:
+ **Construct the execution that breaks a suspicion before calling it a finding.** Where the implementation permits:
- - make a **requested** value differ from the **accepted or effective** one;
+ - 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:
+ **Probe authority reconciliation and identity correlation explicitly.** Strong agents almost never even report these two classes: they miss them at the look, not at the fix. Naming them in a checklist does not make agents inspect them.
- 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.
+ 1. **Authority reconciliation.** Follow a proposed value through validation, normalisation, negotiation or commit. Find downstream state still derived from the proposal where the authority can return something different. A requested value is not an applied value. Force them apart and ask what still reads the request.
+ 2. **Identity correlation.** Trace how an operation's result finds its originating entity. Establish that the key stays unique, stable and live long enough under overlap, reordering, removal and reuse. A label, position or arrival order is suspicious exactly when those properties can fail. 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.
+ The full thirteen diagnostic lenses, each with a detection tell, are in `references/correctness-taxonomy.md`. They overlap; they are not a quota to fill.
## Refutation: the discipline that makes this worth running
- A candidate becomes a finding only with all five:
+ **Require all five elements before promoting a candidate to a finding.** Each finding needs:
- 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.
+ 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.
+ Actively hunt for the refutation. Look for an enclosing guarantee making the execution impossible, synchronisation excluding the interleaving, or reconciliation before any consequential read. Also check intentional contracts, input-excluding preconditions and a different responsible owner.
| 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*. |
+ | Keep | Evidence establishes the defect; the checked counterargument does not prevent it. |
+ | Drop | Cited evidence defeats the execution, obligation or 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.
+ **A correctness defect can harm only the person who triggered it and still be serious.** Do not import security's attacker/victim test into correctness. "Keep unless disproved" is also too permissive: an ungrounded suspicion without a 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.
+ **Absorption is not prevention.** A cache that usually holds, retry that usually succeeds or default that is usually right can hide a defect downstream. That is a coincidence with good odds, not a guarantee. It fails when the absorber is cold, evicted or reconfigured. Drop only on a mechanism that makes the execution impossible, and name that mechanism.
- 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.
+ **"it works nearly always" describes a race, not a refutation.** A timing window that usually resolves correctly is a finding. Having to reason about which side usually wins is the evidence.
+ **Deduplicate by violated agreement and root cause, never by file.** Passing tests, unfamiliar code, a suspicious name, a missing test and a sibling difference warrant investigation. None is proof, and none is refutation. There is no findings quota; zero supported findings is valid.
+
## 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.
+ **Partition complete flows or connected agreement groups, never files or taxonomy classes.** File partitions hide the cross-boundary defects the review should find.
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.
+ 2. Each worker gets a bounded flow, its participants, 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.
+ 5. The coordinator reconciles assumptions and relationships crossing assignments.
+ 6. Strong candidates get a separate verification pass before reporting.
- **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.
+ **Allow overlapping reads.** Reading the same authority twice costs less than either worker holding half its contract. Keep integration capacity in reserve: a relationship spanning assignments stays unexamined until someone closes it. Target one fan-out level. When 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.
+ **Run workers on the strongest model available, and match the current session's effort level.** Recall comes first: a missed cross-boundary flow is the costly failure. A cheaper model or lower effort can lose one. Report which workers were rerouted or downgraded; otherwise readers will misjudge coverage.
- **One model. Name it on every worker.** Fan-out here buys coverage, not a second opinion. Pass the
- coordinator's own model explicitly on each spawn — "inherit" is not a routing decision, and a worker
- that quietly lands on a cheaper model is the easiest way to lose a finding. **Do not bring in a
- different model**, to review or to cross-check, unless you are explicitly asked: mixing models makes
- the result unattributable, and when this skill is being measured or compared across models, one
- foreign worker invalidates the number. The independent pass by a fresh reviewer is a separate
- step (the `independent-review` skill, which the release gate and the ship check's Step 6 call), never something this skill reaches for on its own.
+ **One model. Name it on every worker.** Pass the coordinator's own model explicitly on each spawn. Fan-out buys coverage, not a second opinion. "Inherit" is not a routing decision. Never bring in a different model to review or cross-check unless explicitly asked. Mixing models makes results unattributable; a foreign worker invalidates a comparison across models. The `independent-review` skill supplies the separate pass called by `release-gate` and the ship check's Step 6. This skill never reaches for it on its own.
- **Tell workers they are reading, not editing.** A review worker needs to read, search and navigate;
- it must not modify the tree. State that in the worker's instructions — a worker that starts editing
- drifts from reviewing into "helpfully" fixing and stops reporting what it silently repaired, and the
- findings can no longer be checked against the code they describe. Say it in the prompt rather than
- assuming the host will enforce it, and confirm the tree is unchanged when the run ends.
+ **Tell workers they are reading, not editing.** They need read, search and navigation access, and must not modify the tree. State that in their instructions rather than assuming host enforcement. Editing silently repairs what workers should report and prevents checking findings against the described code. Confirm the tree is unchanged when the run ends.
## Report
- Lead with supported findings, ordered by impact. Keep severity separate from evidential strength.
+ **Lead with supported findings ordered by impact, separating severity from evidential strength.** Use this contract:
```
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.
+ Cite both participants for a cross-boundary defect. Do not group findings only by file; that hides the relationship being reviewed.
- **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.
+ **Coverage means work performed, not boxes ticked.** Report each selected sub-case as examined with supported findings; examined, none supported; not applicable, with reason; or not examined, with reason. Zero findings does not mean "not covered", and ticks are not completeness evidence. Say "no supported findings in the examined scope", never that the code is bug-free.
+ Each rule's origin, the case that taught it, is in `receipts.md` beside this file; read it when a rule's edge is unclear.
+
## How you can tell it worked
Every finding names an execution that breaks an agreement, survived its own refutation, and cites both sides with file and line; nothing reported is style.
## Notes
- - Say explicitly what is well built. A review that only accuses is easy to dismiss.
- - The two sub-cases have mature skills behind them: `security-audit-static` (trust boundaries,
- sinks, OWASP backstop) and `performance-audit-static` (over-fetching, indexes, caching). Apply
- that skill 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.
+ **State what is well built and the limits of static review.** A review that only accuses is easy to dismiss. Static review produces code-review findings, not confirmed exploits or measured regressions.
+
+ **Apply a sub-case's mature skill when that sub-case is the whole job.** Apply `security-audit-static` for trust boundaries, sinks and the OWASP backstop, or `performance-audit-static` for over-fetching, indexes and caching. Use its reference file when it is one dimension of a broader review; this skill does not restate either. For the doc-vs-code axis, apply the `intended-vs-implemented` skill.