Ruby Optimizer

Ruby 4.0.9 is current (Ruby 3.4 and 3.3 are supported; 3.2 is EOL). Performance is allocations/GC, ActiveRecord query shape and background-job concurrency; YJIT/bootsnap and jemalloc help but do not fix N+1. Optimize measured production workloads, not micro-benchmarks.

Workflow

1. Scope (quick)

• Find the project root and record the toolchain: Ruby version/YJIT, Bundler and gems, framework (Rails/Sinatra), web server (Puma), job system (Sidekiq), database/ActiveRecord, caching and deployment.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of build files and sources for EOL Ruby, missing YJIT/bootsnap, allocations/GC, N+1 and missing indexes, job concurrency, thread/fiber safety, rescue/security traps, with file:line evidence. Use --json to post-process.
• Classify the pain: throughput/latency, memory growth, CPU saturation, concurrency/correctness, I/O or database cost, build/startup, or safety/maintenance. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here.

2. Audit

The script finds cheap leads; you find the rest by reading the hot path and the build. Read the build manifest, entrypoint, the 3-5 hot functions/endpoints and the data layer. Load only what applies:

| Build, runtime and server | references/build-runtime.md | | Memory and concurrency | references/memory-concurrency.md | | I/O, ActiveRecord and jobs | references/io-data.md | | Safety and quality | references/safety-quality.md | | Measurement | references/tooling.md |

Measure, never guess. Build with production settings, run with production data/load, and profile that. Debug builds, dev servers and a single request are not evidence. Take a profile before micro-optimizing and a heap/allocator snapshot before raising limits.

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

3. Report

Fill assets/report-template.md, save it as RUBY_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, behavior impact). Group near-duplicates.

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 -- build flags, missing indexes/caching, timeouts/pool limits, avoidable allocations/copies, sync I/O in hot paths, missing await/join, safer bounds checks, log noise, config limits. Low risk.
2. Structural -- bound concurrency, batch N+1, stream large payloads, change data structures/ownership, split hot paths, cache correctly, connection/worker pools, graceful shutdown, observability. Name each behavior change.
3. Heavy -- language/toolchain major upgrade, runtime/GC change, framework/ORM swap, architecture change, AOT/trimming, database migration. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: build with production flags, run the test suite, and re-run the same benchmark/profile. A break must trace to one change. Do not mix a toolchain major upgrade with optimization edits. If a change alters ownership, concurrency, API/DB semantics or failure behavior, stop and ask.

6. Verify and wrap up

Re-measure the same workload and data: throughput and p50/p95/p99, CPU, RSS/heap, allocations/GC, I/O, error rate, build time and binary/image size. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• Ruby 4.0 is current. 3.3 is security maintenance; 3.2 is EOL.
• Query shape beats Ruby micro-tuning. N+1 and missing indexes dominate.
• Allocations are GC. Frozen strings, pluck, find_each and fewer intermediate arrays.
• Concurrency respects the GVL. Threads help I/O; CPU work needs processes/Ractors or a job system.
• Measure with production data. Dev-mode reloading and small datasets hide the cost.

Docs

• https://www.ruby-lang.org/en/documentation/