| 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
- Read local instructions, docs, relevant code, and tests.
- Identify language/runtime, entry points, expected inputs/outputs, public APIs, domain assumptions, and changed behavior.
- Inspect surrounding code, not only the edited lines.
- Separate confirmed issues from risks and questions.
- 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
- Correctness and scientific correctness.
- Reproducibility and validation.
- Tests and error handling.
- Maintainability.
- Performance.
- Security/safety.
- 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. ...
