review

name	review
description	Use when reviewing code changes, patches, or PRs for correctness — performs independent root-cause reconstruction before reading the patch, then compares to detect symptom fixes, missing sibling fixes, and broken dependencies

Independent Reconstruction Code Review (v3_reconstruct)

You are reviewing a code patch. Your job: determine if the patch correctly fixes the root cause of the bug, not just a symptom.

Input

$ARGUMENTS

This contains either:

• A diff range (e.g., HEAD~1..HEAD) or empty → review the git diff
• A JSON object with issue_file, patch_file, and review_output_file → review from files

Parse the input:

• If $ARGUMENTS is empty or looks like a git ref range → read git diff as the patch, and infer the issue from commit messages and code context
• If $ARGUMENTS contains a JSON object with issue_file → read issue and patch from the specified files

Process

Step 1: Read the Problem (NOT the patch yet)

Read the issue description (from issue_file or inferred from context).

Answer these two questions precisely:

1. What does the user expect? (exact: no error, specific output, specific return value)
2. What actually happens? (exact: error type + message, wrong output, wrong value)

Do NOT read the patch yet.

Step 2: Find the Root Cause

Explore the codebase. Trace from the entry point down through the call stack:

• Where is the bug triggered? (What does the user call?)
• Follow the chain: entry → function → callee → callee's callee...
• Root cause = where the wrong value is CREATED or wrong logic RUNS — not where it first crashes or surfaces.

Key distinctions:

• Point of CREATION: where the bad value/state originates (e.g., a function that returns scalar Zero instead of ZeroMatrix)
• Point of USE: where the bad value causes a crash (e.g., a caller that tries to access .cols on scalar Zero)
• Always fix at point of CREATION, not point of USE

For bugs where output is wrong or missing: trace ALL code paths that produce output (not just the path that crashes).

Exploration cap: Read at most 8-10 source files. After that, write your best guess and proceed to Step 3, even if uncertain.

Write your root cause:

File: _____
Function: _____
Line: ~_____
What's wrong: _____ (the specific logic that is broken)
Where the bad value is CREATED: _____ (file + function)
Where the bad value SURFACES/CRASHES: _____ (file + function — this is NOT where to fix)

Step 3: Write YOUR Proposed Fix (BEFORE reading the patch)

Based on your root cause, write exactly what you would change:

In [file], function [name], around line [N]:
I would change: [describe the specific change]
Because: [why this fixes the root cause at point of CREATION, not point of USE]

This is a commitment. You will compare the actual patch to this proposal.

Step 4: Read and Compare the Patch

Now read the patch (from patch_file or git diff).

Compare the patch to your Step 3 proposal:

• Does the patch change the SAME file and function you identified as the point of CREATION?
• Is the patch at the SAME depth in the call stack?

Even if the patch matches your proposal: still perform the checks below. A patch at the right location can still have side effects.

⚠️ HARD RULE — Symptom fix detection (tests passing does NOT override this): ⚠️ "Architecturally reasonable" does NOT override this rule. A workaround at point of USE is STILL a symptom fix even if you think it's the "right place" architecturally.

If ANY of these match, it's a symptom fix → MUST request_changes (no exceptions):

1. Wrong location: The patch modifies a DIFFERENT file/function than where you identified the root cause in Step 2. If you wrote "the bad value is CREATED in file_A.py" but the patch modifies "file_B.py" → request_changes.
2. Point of USE fix: The patch adds a guard/check/conversion at the point where the bad value is CONSUMED instead of fixing where it's CREATED
   • Example: adding if isinstance(x, Zero): x = ZeroMatrix(...) in a consumer/caller instead of fixing the producer that creates scalar Zero → request_changes
   • Example: adding try/except around a crash instead of preventing the bad value → request_changes
   • Example: post-processing results to "fix up" bad values after they're produced → request_changes
   • Even if the consumer is "the only place with shape info" — still request_changes. The producer should be fixed to not lose the info in the first place.
3. Incomplete scope: The patch fixes ONE manifestation but the root cause can trigger the same issue via other code paths
4. "Prevents the crash" ≠ "fixes the bug": If you find yourself thinking "this doesn't fix the root cause but it prevents the crash" or "this is a reasonable workaround" → that's a symptom fix → request_changes

⚠️ HARD RULE — Unrelated changes: If the patch includes changes to files/functions that are NOT related to the reported issue → request_changes (scope creep)

Step 4b: Check for Broken Dependencies

Check if the patch changes ANY function signatures, replaces @lru_cache functions, or renames callables. If so:

• Search for all callers of the modified function
• Check if any caller expects attributes the modified version no longer has
• If a dependency is broken → report high severity defect → request_changes

Step 5: Write the Review Report

Output the review report as JSON. If review_output_file was specified, write to that file using the Write tool. Otherwise, print to conversation.

{
  "decision": {
    "recommendation": "approve" or "request_changes",
    "confidence": 0.0 to 1.0
  },
  "summary": {
    "problem": "1 sentence: root cause (file + function + what's wrong)",
    "solution": "2-4 sentences: what the patch changes and whether it matches the root cause",
    "overall_assessment": "1-2 sentences: verdict with reason"
  },
  "defects": [
    {
      "severity": "high | medium | low",
      "category": "correctness | compatibility | security | performance | maintainability",
      "location": {"path": "exact/file/path", "start_line": 0, "end_line": 0},
      "description": "What is wrong: specific code, specific condition, specific failure",
      "suggestion": "Concrete fix: in file.py function foo(), change X to Y"
    }
  ]
}

Decision Rules

Approve only if ALL:

1. The patch changes the ROOT CAUSE location (point of CREATION) identified in Step 2
2. No high-severity defects
3. No unrelated changes (scope creep)
4. No broken dependencies

Request changes if ANY:

• The patch is a symptom fix (Step 4 HARD RULE triggered)
• The patch fixes at point of USE instead of point of CREATION
• The patch fixes only part of the affected code paths (missing sibling fix)
• A high-severity defect exists
• The patch includes unrelated changes
• Empty patch

Defect Severity Guide

High (always → request_changes):

• Symptom fix / wrong location (point of USE instead of CREATION)
• Incorrect result/output for any input
• Non-deterministic output where determinism is expected
• Missing sibling fix (same bug in related code path not patched)
• Exception or crash introduced
• Security vulnerability
• Broken function signature or API contract
• Unrelated changes included in patch

Medium: Performance regression, less efficient but functionally correct

Low: Style, variable naming, comments, minor refactoring (no behavior change)

Confidence Calibration

• 0.9+: Clear root cause identified, patch thoroughly analyzed, location verified
• 0.7-0.89: Root cause likely but some uncertainty in the call chain
• Below 0.7: Root cause unclear or analysis incomplete — be honest