Rust Optimizer

Audit a Rust codebase, report what is slow and why, agree a plan with the user, then fix it. Order matters: evidence first, approval second, edits last. Performance edits in Rust often change ownership, lifetimes, public APIs or unsafe surface, so nothing is edited before the user approves.

Workflow

1. Scope (quick)

• Find the root: the Cargo.toml (workspace root if [workspace]). Note toolchain (rust-toolchain.toml, rustc --version), edition, MSRV (rust-version), target OS.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of Cargo manifests (release profile, allocator, feature bloat, deprecated deps) and .rs sources (blocking in async, locks across await, regex in loops, clone-in-loop, unwrap density, unsafe, N+1 hints) with file:line evidence. --json for post-processing.
• Classify the workload before advice: CPU-bound, IO/async service, memory-bound, startup/binary-size sensitive, or build-time pain. Advice differs completely. Ask the user which one hurts if unclear.
• Read references/tooling.md once to know which measuring tools are installed (cargo flamegraph, samply, hyperfine, cargo bloat, cargo build --timings) and what to propose installing.

2. Audit

The script finds cheap leads; you find the rest by reading the hot path. Read the root Cargo.toml, main.rs/lib.rs, the 3-5 functions the user cares about or a profile points at. Load only the references that apply:

Measure, never guess. Debug builds are meaningless for performance: only --release counts. Profile before editing; a flamegraph of the real workload beats any checklist. If a tool is missing or the workload can't be run, say measurement wasn't possible instead of inventing numbers.

Mark each finding Confirmed (profile/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save as RUST_OPTIMIZATION_REPORT.md in the project root, and show the user. 5-line summary, findings table sorted by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, API/semver impact). Group related findings.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable, show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- [profile.release] tuning, allocator swap, feature trimming, with_capacity, hoisting Regex::new, spawn_blocking for blocking calls. Low risk, no API change.
2. Structural -- remove clones via borrowing/Cow/Arc/Bytes, iterator rewrites, async lock redesign, batching queries, channel backpressure. Name every behaviour change.
3. Heavy -- dependency swaps, PGO/BOLT, public API changes, unsafe or SIMD, architecture changes. Separately approved; unsafe only with a measured win and a safety comment. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, small groups. After each group run cargo fmt --check, cargo clippy --all-targets -- -D warnings (if the project already passes it), and cargo test. A break must trace to one change. Do not mix a toolchain/edition upgrade with optimization edits. If something turns out riskier than planned (API break, changed error semantics, new unsafe), stop and ask.

6. Verify and wrap up

Re-measure with the same command and inputs as before; report before/after (wall time via hyperfine, bench medians, peak RSS, allocation counts, binary size, cargo build --timings total). State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Algorithm and data structure first, micro-tweaks last. An O(n^2) scan or a Vec::contains in a loop dwarfs any LTO flag.
• Allocation is the usual Rust cost. Count it (dhat, heaptrack) before rewriting; fix the top call sites, not every .clone().
• A clone is fine until the profile says otherwise. Don't contort lifetimes for cold code; readability is a feature.
• Async is not parallelism. Blocking inside async tasks and locks held across .await are correctness bugs first, performance bugs second.
• Release-mode, representative data, warm caches, several runs. One run on a laptop under load proves nothing; report medians.
• unsafe needs proof. Require a benchmark showing the win, an invariant comment, and miri/tests; otherwise refuse.
• Docs move. For crate APIs and defaults, check docs.rs for the version in Cargo.lock instead of relying on memory.