code-review

name	code-review
description	Use when reviewing code, tests, scripts, notebooks, configuration, diffs, or physics-analysis workflows for correctness, maintainability, performance, reproducibility, or scientific validity.

Code Review Skill

Review for real issues. Correctness comes first; for HEP work, physics meaning and reproducibility are correctness concerns.

Process

1. Read local instructions, docs, relevant code, and tests.
2. Identify language/runtime, entry points, expected inputs/outputs, public APIs, domain assumptions, and changed behavior.
3. Inspect surrounding code, not only the edited lines.
4. Separate confirmed issues from risks and questions.
5. Lead with findings ordered by severity and grounded in file/line references.

Use these labels:

• Bug: wrong or likely wrong behavior.
• Risk: could fail under specific conditions.
• Question: clarification needed.
• Suggestion: optional improvement.
• Nit: low-priority style issue.

Priority Order

1. Correctness and scientific correctness.
2. Reproducibility and validation.
3. Tests and error handling.
4. Maintainability.
5. Performance.
6. Security/safety.
7. Style.

Do not spend most of the review on formatting unless it blocks correctness or maintainability.

General Checklist

Check for edge cases, type/shape/unit mismatches, off-by-one errors, missing validation, bad parsing, wrong ordering assumptions, hidden global state, non-determinism, broad exception handling, unsafe file handling, broken repeated runs, and behavior that depends on local machine state.

For Python, also check pandas chained assignment, NumPy broadcasting, dtype/shape assumptions, filesystem Path use, CLI validation, seed control, notebook execution-order dependence, and accidental mutation of inputs.

For C/C++/CUDA, check ownership, lifetimes, bounds, undefined behavior, accidental hot-path copies/allocations, ABI changes, CUDA indexing, stream use, synchronization, transfers, races, atomics, memory coalescing, register pressure, and numerical drift.

For shell, check quoting, set -euo pipefail where appropriate, unsafe rm/cp/mv, temp files, cwd/tool assumptions, leaked secrets, and prompts that block automation.

Physics Analysis Review

Use for HEP, LHCb, ROOT, RooFit, zfit, histograms, ntuples, fitting, selections, efficiencies, plots, systematics, or statistical workflows.

Check:

• Dataset/sample provenance: year, polarity, trigger/stripping line, data-vs-MC separation, tree/branch names, duplicates, file ordering, friend alignment, event IDs, and local-path dependence.
• Selection logic: cut direction, units, boolean masks, object alignment, hidden preselections, blinding, sideband/signal definitions, trigger overlaps, and agreement with notes/thesis text.
• Weights/normalization: denominator/numerator definitions, per-event vs per-candidate weights, negative weights, missing branches, uncertainty propagation, sumw2, and year/PID/tracking/trigger factors.
• ROOT/histograms: ownership/lifetimes, overflow/underflow, binning, variable ranges, output names, metadata, and overwrite behavior.
• Fits/statistics: observable/range, binned vs unbinned, extended likelihood, fixed/constrained/floated parameters, normalization range, fit/Hesse/Minos status, pulls, toys, correlations, coverage, and uncertainty interpretation.
• ML in analysis: sample leakage, truth-only features, preprocessing split, threshold choice, overtraining checks, calibration, and inference/training mismatch.
• Reproducibility: input lists, versions, seeds, config separation, deterministic outputs, plot labels, clean-checkout runability, and traceable final numbers.

Ask for missing physics definitions when they determine correctness.

Test and Performance Review

Tests should cover normal, empty, bad, boundary, regression, CLI/file-output, numerical-tolerance, and domain-invariant cases as relevant.

Prioritize performance only for hot paths, large data, explicit performance requests, or clearly unsuitable scaling. Prefer measured bottlenecks over speculative rewrites.

Output

For general reviews:

Findings:

- [severity] `file:line` issue and impact.

Questions:

- ...

Summary:

- ...

For physics reviews:

Physics correctness:

- ...

Software correctness:

- ...

Reproducibility:

- ...

Tests and validation:

- ...

High-priority fixes:

1. ...