Design multi-instance and multi-pass review architectures

Why a model is a poor reviewer of its own work

When a model generates code and is then asked, in the same session, to review it, it still holds the reasoning that produced that code. Every design decision already looks justified, because the justification is right there in context. The result is that self-review is less likely to question its own decisions — it tends to confirm rather than challenge. This is a context property, not a capability shortfall. That is why the guide is explicit that independent review instances, running without the generator's prior reasoning context, catch subtle issues more effectively than either a self-review instruction ("now critically review your work") or extended thinking.⁵³ Adding more reasoning inside the same context does not remove the bias built into that context.

Practically: for generated code, spin up a second Claude instance that receives the code and the requirements but not the generation transcript.¹⁵ It has to reconstruct intent from the artifact, which is exactly what a human reviewer does and exactly what surfaces the assumption the generator never questioned.

Multi-pass review: the pass taxonomy and the merge rule

Why a single giant pass degrades is covered in full in 1.6 — attention dilution, contradictory findings inside one PR, and why a larger context window is not the remedy. Here the subject is the shape of the decomposition and what becomes of the findings afterwards.

The taxonomy has exactly two pass types, each defined by the question it can answer.

Pass type	The question it answers	What it structurally cannot answer	Wins the merge on
Per-file local pass — one per changed file, sees that file's diff	logic errors, error handling, unchecked inputs	whether callers satisfy this file's new preconditions	line-level questions — the only pass that saw the file in detail
Separate integration pass — one per data flow, sees the changed contracts and every call site touching them	cross-file data flow: does the emitted type match what the consumer expects, does the caller apply the discount the callee assumes, does a contract change break a distant call site	line-level detail inside unrelated files	contract and data-flow questions — the only pass that saw both sides

Because the two types answer different questions they get different prompts, and they produce two finding sets that must be merged rather than concatenated.⁴⁵ The merge rule falls straight out of the taxonomy:

1. Dedupe on (location, detected_pattern).
2. Resolve each collision in favor of the pass that could see the answer, as the last column above records.
3. Pass through untouched any finding that only one pass type could have produced.

Verification passes with self-reported confidence

The third technique is a verification pass in which the model self-reports confidence alongside each finding, so findings can be routed by calibration. High-confidence findings post automatically as PR comments, low-confidence findings go to a human triage queue, and the rest are dropped or batched. Note the careful distinction against 4.1 — confidence is used downstream, as routing metadata on an already-generated finding, not upstream as the criterion that decides whether the model should report at all. Asking the model to filter by confidence during finding does not improve precision; asking it to label findings with confidence so your pipeline can route them does add value.

Two preconditions bound that value, and both live in Domain 5:

• The thresholds must be calibrated. A self-reported "high" is not a probability until you have measured what it means. The procedure is 5.5's: have the model emit field-level or finding-level confidence, then set the routing thresholds against a labeled validation set, so "auto-post above this level" reflects a measured accuracy rather than an assumption. An uncalibrated threshold is 4.1's anti-pattern wearing a number.
• Routing is not escalation. Confidence is never the trigger for handing a live conversation to a human (5.2). Official Sample Question 3 rejects precisely that option: the agent is already incorrectly confident on the hard cases, so a confidence threshold escalates the easy ones and keeps the hard ones. Explicit escalation criteria with few-shot examples are the credited fix there. Routing works here because a finding already exists and is being sorted offline against calibrated data; escalation fails because the decision must be made in-flight by the same miscalibrated model.

// Pass 1 -- generation. This conversation holds all the design reasoning.
const generation = await client.messages.create({
  model: 'claude-opus-5',
  max_tokens: 8192,
  messages: generatorHistory,     // requirements, exploration, revisions
});
const code = extractCode(generation);

// Pass 2 -- review by an INDEPENDENT instance. Fresh message list:
// the generator's reasoning is deliberately NOT carried over.
const review = await client.messages.create({
  model: 'claude-opus-5',
  max_tokens: 8192,
  system: reviewerCriteria,       // explicit report/skip criteria (4.1)
  tools: [reportFindings],        // schema-enforced findings (4.3)
  tool_choice: { type: 'tool', name: 'report_findings' },
  messages: [{ role: 'user', content: renderReviewRequest(requirements, code) }],
});

// Anti-pattern for contrast:
//   generatorHistory.push({ role: 'user', content: 'Now review your own code.' })
// -- same session, same reasoning context, confirms rather than challenges.

LOCAL PASSES  (one per changed file, N = 40)
  Input:  the single file's diff + surrounding context for that file
  Asks:   logic errors, unchecked inputs, error handling, resource leaks
  Cannot: judge whether callers satisfy this file's new preconditions

INTEGRATION PASSES  (grouped by data flow, N = 4)
  Input:  the signatures/contracts that changed + every call site touching them
  Asks:   type and contract mismatches across module boundaries,
          state mutated in one module and read in another,
          a precondition assumed by the callee and not met by the caller
  Cannot: see line-level detail inside unrelated files

MERGE  (a reconciliation, not a concatenation)
  1. Dedupe on (location, detected_pattern).
  2. On a collision, the pass that could see the answer wins:
       contract / data-flow question  -> integration finding
       line-level question            -> local finding
  3. Findings only one pass type could produce pass through unchanged.

  Result: one finding set in which no two entries disagree about the same
  construct, because each question type has exactly one authoritative pass.

TAIL
  A verification pass then attaches self-reported confidence to each merged
  finding, and the pipeline routes on it -- thresholds calibrated against a
  labeled validation set (5.5), never used to escalate a live conversation.

[
  {
    "location": "src/billing/invoice.ts:88",
    "issue": "total computed before discount is applied",
    "severity": "HIGH",
    "detected_pattern": "reduce_over_items_without_discount_call",
    "confidence": "high",
    "route": "post_as_pr_comment"
  },
  {
    "location": "src/sync/worker.ts:142",
    "issue": "possible race on the cursor when two workers start together",
    "severity": "MEDIUM",
    "detected_pattern": "shared_cursor_without_lock",
    "confidence": "medium",
    "route": "human_triage_queue"
  }
]