review-rust

Rust Code Review

Arguments

• --parallel: Spawn specialized subagents per technology area
• Path: Target directory (default: current working directory)

Hard gates

Complete in order before writing Issues in the output (empty scope is allowed; fabricated findings are not).

1. Scope gate: You have an explicit list of .rs paths under review (from Step 1 or the user-provided path). Pass: List printed or "No Rust files in scope" — then stop with no Issues.
2. Compiler/linter gate: Step 3 commands were run from the crate or workspace root (Cargo.toml present); if they cannot run, one line states why (e.g. missing toolchain, no Cargo.toml, sandbox). Pass: You do not report a problem already shown as an error/warning in Step 3 output, and you do not duplicate compiler or clippy diagnostics the author must fix first.
3. Protocol gate: beagle-rust:review-verification-protocol is loaded before Step 7. Pass: Every Critical/Major finding satisfies Step 8 (and the protocol); if there are zero findings, say "Protocol applied; no issues" in the Review Summary.
4. Evidence gate (Critical/Major): For each Critical or Major item, you re-read the file at FILE:LINE with full surrounding context (not only the diff hunk). Pass: The Issue description matches observable code at that location.

Step 1: Identify Changed Files

git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '\.rs$'

Step 2: Check Rust Edition and MSRV

# Check Cargo.toml for edition and rust-version
grep -E 'edition|rust-version' Cargo.toml

# Check workspace members if workspace
grep -A 20 '\[workspace\]' Cargo.toml

Edition 2024 awareness (requires MSRV 1.85+):

If edition = "2024" is detected, the following behavioral changes apply throughout the review:

• unsafe_op_in_unsafe_fn is deny by default — unsafe operations inside unsafe fn MUST use explicit unsafe {} blocks
• extern "C" {} blocks must be unsafe extern "C" {}
• #[no_mangle] and #[export_name] must be #[unsafe(no_mangle)] and #[unsafe(export_name)]
• -> impl Trait captures ALL in-scope lifetimes by default (RPIT lifetime capture change); use + use<'a> for precise capture
• gen is a reserved keyword — code using it as an identifier must use r#gen
• ! (never type) falls back to ! instead of () — may change behavior of inferred types
• Temporaries in if let conditions and tail expressions are dropped earlier than in edition 2021
• Box<[T]> now implements IntoIterator

Record the detected edition — it affects severity calibration in Steps 3, 8, and the verification protocol.

Step 3: Verify Linter Status

CRITICAL: Run clippy and check BEFORE flagging style or correctness issues. Do NOT flag issues that clippy or the compiler already catches.

cargo clippy --all-targets --all-features -- -D warnings 2>&1 | head -50
cargo clippy -- -D clippy::perf 2>&1 | head -20
cargo check --all-targets 2>&1 | head -50

Edition 2024 note: Edition 2024 promotes several previously-warn lints to deny (notably unsafe_op_in_unsafe_fn). If clippy or cargo check already reports edition-related errors, do not duplicate those as review findings — instead note that the author must fix compiler errors first.

Step 4: Detect Technologies

# Detect tokio async runtime
grep -r "tokio" --include="Cargo.toml" -l | head -3

# Detect axum web framework
grep -r "axum" --include="Cargo.toml" -l | head -3

# Detect sqlx database
grep -r "sqlx" --include="Cargo.toml" -l | head -3

# Detect serde serialization
grep -r "serde" --include="Cargo.toml" -l | head -3

# Detect thiserror / anyhow
grep -r "thiserror\|anyhow" --include="Cargo.toml" -l | head -3

# Detect tracing
grep -r "tracing" --include="Cargo.toml" -l | head -3

# Check for test files in diff
git diff --name-only $(git merge-base HEAD main)..HEAD | grep -E '((^|/)(test|tests)/.*\.rs$)|(_test\.rs$)'

# Check for unsafe code in diff
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -c 'unsafe'

# Detect async fn in traits (no async-trait crate needed since Rust 1.75)
grep -r "async-trait" --include="Cargo.toml" -l | head -3

# Detect LazyLock/LazyCell usage (replaces once_cell/lazy_static since 1.80)
grep -r "once_cell\|lazy_static" --include="Cargo.toml" -l | head -3

# Detect #[expect] lint attribute usage (stable since 1.81)
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -c '#\[expect('

# Detect macro definitions in diff
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'macro_rules!|#\[proc_macro|#\[derive\('

# Detect FFI code in diff
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'extern "C"|#\[no_mangle\]|#\[repr\(C\)\]|bindgen|#\[unsafe\(no_mangle\)\]'

# Detect concurrency primitives (atomics, lock-free, hand-rolled sync)
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'std::sync::atomic|Atomic(Bool|U?size|U?(8|16|32|64)|Ptr)|compare_exchange|fetch_(add|sub|or|and|xor|update)|UnsafeCell|unsafe impl (Send|Sync)|Ordering::(Relaxed|Acquire|Release|AcqRel|SeqCst)|atomic::fence'

# Detect concurrency test tooling
grep -rE 'loom|^miri$' --include='Cargo.toml' -l | head -3
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'loom::|#\[cfg\(loom\)\]|cfg_attr\(miri'

# Detect concurrency crates
grep -rE '^crossbeam|^arc-swap|^parking_lot|^dashmap|^flurry|^haphazard|^seize|^atomic_wait' --include='Cargo.toml' -l | head -3

# Detect criterion benchmarks
grep -rE '^criterion' --include='Cargo.toml' -l | head -3
ls -d benches 2>/dev/null

# Detect proc-macro crate or trybuild
grep -rE 'proc-macro\s*=\s*true|^trybuild' --include='Cargo.toml' -l | head -3

# Detect public-surface changes (interface-design.md routing)
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE '^\+\s*pub (trait|fn|struct|enum|mod|use)|^\+\s*impl[<\s].*Drop for'

# Detect ecosystem patterns (patterns-in-the-wild.md routing)
grep -rE '^slotmap|^petgraph|^scopeguard|^indexmap' --include='Cargo.toml' -l | head -3
git diff $(git merge-base HEAD main)..HEAD -- '*.rs' | grep -cE 'mem::replace|swap_remove|prelude'

Modern Rust detection notes:

• If async-trait is a dependency but the project uses edition 2024 or MSRV >= 1.75, flag as Informational — native async fn in traits is available and async-trait can likely be removed.
• If once_cell or lazy_static is a dependency but MSRV >= 1.80, flag as Informational — std::sync::LazyLock and std::cell::LazyCell are stable replacements.
• If #[allow(...)] is used where #[expect(...)] would be better (MSRV >= 1.81), note as Minor — #[expect] warns when the suppressed lint no longer fires, keeping suppressions clean.

Concurrency detection notes:

• If atomics (std::sync::atomic, compare_exchange, fetch_*), UnsafeCell, unsafe impl Send/Sync, or crossbeam / arc-swap / parking_lot are present in the diff, load beagle-rust:rust-code-review and consult references/concurrency-primitives.md, references/memory-ordering.md, and references/lock-free-patterns.md.
• If the diff introduces or restructures concurrency (worker pools, actor-style channels, tokio::spawn patterns, threads-vs-async choices), also consult references/concurrency-models.md for design-level review questions.
• If hand-rolled atomics / lock-free types appear with no loom dependency or no cargo +nightly miri test in CI, load beagle-rust:rust-testing-code-review and consult references/concurrency-testing.md.

Interface design / API surface detection:

• If the diff introduces or changes pub trait, pub fn, pub struct, derive impls on public types, impl Drop on owning types, or re-exports of foreign types, load beagle-rust:rust-code-review and consult references/interface-design.md for object-safety, ergonomic-impl, fallible-destructor, and hidden-contract review checks.
• If the diff uses index-pointer graphs (Vec<Node> + usize, slotmap, petgraph), mem::replace-style drop guards, extension traits, or modifies a prelude module, also consult references/patterns-in-the-wild.md.

Testing detection (criterion / trybuild / clippy strategy):

• If benches/ directory or criterion dependency is present, load beagle-rust:rust-testing-code-review and consult references/advanced-testing.md for criterion baseline, black_box, and iter_batched review checks.
• If proc-macro crate (proc-macro = true) or trybuild in [dev-dependencies], consult references/advanced-testing.md for trybuild .stderr stability checks plus beagle-rust:macros-code-review references/procedural-macros.md for span hygiene and syn feature audits.

Step 5: Load Verification Protocol

Load beagle-rust:review-verification-protocol skill and keep its checklist in mind throughout the review.

Step 6: Load Skills

Use the Skill tool to load each applicable skill (e.g., Skill(skill: "beagle-rust:rust-code-review")).

Always load:

• beagle-rust:rust-code-review

Conditionally load based on detection:

Condition	Skill
Tokio detected	beagle-rust:tokio-async-code-review
Axum detected	beagle-rust:axum-code-review
sqlx detected	beagle-rust:sqlx-code-review
Serde detected	beagle-rust:serde-code-review
Test files changed	beagle-rust:rust-testing-code-review
Macro definitions in diff	beagle-rust:macros-code-review
FFI code detected (extern, repr(C), bindgen)	beagle-rust:ffi-code-review
Atomics, UnsafeCell, unsafe impl Send/Sync, compare_exchange, crossbeam, arc-swap, parking_lot	beagle-rust:rust-code-review (load references/concurrency-primitives.md, references/memory-ordering.md, references/lock-free-patterns.md)
Concurrency design changes (worker pools, channels, threads-vs-async restructuring)	beagle-rust:rust-code-review (load references/concurrency-models.md)
Public trait / pub fn / pub struct / impl Drop / re-export changes	beagle-rust:rust-code-review (load references/interface-design.md)
Graph/tree code, slotmap, petgraph, mem::replace drop guards, extension traits, prelude module changes	beagle-rust:rust-code-review (load references/patterns-in-the-wild.md)
criterion benchmarks, benches/ directory	beagle-rust:rust-testing-code-review (load references/advanced-testing.md — criterion baseline + black_box + iter_batched checks)
Proc-macro crate (proc-macro = true) or trybuild in dev-deps	beagle-rust:rust-testing-code-review + beagle-rust:macros-code-review (load references/advanced-testing.md trybuild + references/procedural-macros.md span hygiene)
loom, miri, hand-rolled lock-free code under test	beagle-rust:rust-testing-code-review (load references/concurrency-testing.md)

Step 7: Review

Sequential (default):

1. Load applicable skills
2. Review core Rust quality (ownership, error handling, unsafe, traits)
3. Review detected technology areas
4. Consolidate findings

Parallel (--parallel flag):

1. Detect all technologies upfront
2. Spawn one subagent per technology area with Task tool
3. Each agent loads its skill and reviews its domain
4. Wait for all agents
5. Consolidate findings

Step 8: Verify Findings

Before reporting any issue:

1. Re-read the actual code (not just diff context)
2. For "unused" claims - did you search all references across the workspace?
3. For "missing" claims - did you check trait definitions, derive macros, and #[cfg] gated code?
4. For "unnecessary clone" - did you verify the borrow checker allows a reference?
5. For "unsafe" issues - did you check the safety comments and surrounding invariants?
6. Remove any findings that are style preferences, not actual issues

Edition 2024 verification rules: 7. Do NOT flag unsafe {} blocks inside unsafe fn as unnecessary — they are REQUIRED in edition 2024 8. Do NOT flag unsafe extern "C" as unusual syntax — it is REQUIRED in edition 2024 9. Do NOT flag #[unsafe(no_mangle)] or #[unsafe(export_name)] as unusual — they are REQUIRED in edition 2024 10. For -> impl Trait returns, verify whether implicit lifetime capture is intentional — in edition 2024 all in-scope lifetimes are captured by default; suggest + use<'a> only when narrower capture is needed 11. For code using Box<[T]> in iterator contexts, remember IntoIterator is now available in edition 2024 — do not flag .iter() on boxed slices as the only approach 12. If temporaries in if let or tail expressions cause borrow issues, consider whether edition 2024's earlier drop semantics are the root cause

Step 9: Review Convergence

Single-Pass Completeness

You MUST report ALL issues across ALL categories (ownership, error handling, async, types, tests, security, performance) in a single review pass. Do not hold back issues for later rounds.

Before submitting findings, ask yourself:

• "If all my recommended fixes are applied, will I find NEW issues in the fixed code?"
• "Am I requesting new code (tests, types, modules) that will itself need review?"

If yes to either: include those anticipated downstream issues NOW, in this review, so the author can address everything at once.

Scope Rules

• Review ONLY the code in the diff and directly related existing code
• Do NOT request new features, test infrastructure, or architectural changes that didn't exist before the diff
• If test coverage is missing, flag it as ONE Minor issue ("Missing test coverage for X, Y, Z") — do NOT specify implementation details
• Doc comments, naming issues are Minor unless they affect public API contracts
• Do NOT request adding new dependencies (e.g., proptest, mockall, criterion)

Fix Complexity Budget

Fixes to existing code should be flagged at their real severity regardless of size.

However, requests for net-new code that didn't exist before the diff must be classified as Informational:

• Adding a new dependency
• Creating entirely new modules, files, or test suites
• Extracting new traits or abstractions
• Adding benchmark suites

These are improvement suggestions for the author to consider in future work, not review blockers.

Iteration Policy

If this is a re-review after fixes were applied:

• ONLY verify that previously flagged issues were addressed correctly
• Do NOT introduce new findings unrelated to the previous review's issues
• Accept Minor/Nice-to-Have issues that weren't fixed — do not re-flag them
• The goal of re-review is VERIFICATION, not discovery

Output Format

## Review Summary

[1-2 sentence overview of findings]

## Issues

### Critical (Blocking)

1. [FILE:LINE] ISSUE_TITLE
   - Issue: Description of what's wrong
   - Why: Why this matters (unsound unsafe, data race, panic, security)
   - Fix: Specific recommended fix

### Major (Should Fix)

2. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Minor (Nice to Have)

N. [FILE:LINE] ISSUE_TITLE
   - Issue: ...
   - Why: ...
   - Fix: ...

### Informational (For Awareness)

N. [FILE:LINE] SUGGESTION_TITLE
   - Suggestion: ...
   - Rationale: ...

## Good Patterns

- [FILE:LINE] Pattern description (preserve this)

## Verdict

Ready: Yes | No | With fixes 1-N (Critical/Major only; Minor items are acceptable)
Rationale: [1-2 sentences]

Rules

• Complete Hard gates before writing Issues
• Load skills BEFORE reviewing (not after)
• Number every issue sequentially (1, 2, 3...)
• Include FILE:LINE for each issue
• Separate Issue/Why/Fix clearly
• Categorize by actual severity
• Run clippy before flagging style issues
• Run verification after fixes
• Report ALL issues in a single pass — do not hold back findings for later iterations
• Re-reviews verify previous fixes ONLY — no new discovery
• Requests for net-new code (new modules, dependencies, test suites) are Informational, not blocking
• The Verdict ignores Minor and Informational items — only Critical and Major block approval

Post-Fix Verification

After fixes are applied, run:

cargo check --all-targets
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-targets

All checks must pass before approval.