Optimize Performance

Identify and fix performance bottlenecks in Rails applications.

Files: SKILL.md · EXAMPLES.md · references/tools.md

HARD-GATE

NEVER optimize without a baseline measurement
ALWAYS write a regression spec before optimizing (query count assertion)
ALWAYS verify with EXPLAIN ANALYZE for database changes

REPORT ORDER MUST MATCH WORK ORDER:
  1. Baseline measurement
  2. Bottleneck identification (Bullet / rack-mini-profiler / EXPLAIN)
  3. Regression spec written + run + FAILS at the unoptimized count
  4. Fix applied
  5. Regression spec rerun + PASSES at the optimized count
  6. EXPLAIN ANALYZE confirms plan change

NEVER write the report as "I applied includes(:author), then wrote a spec
to lock it in." The spec MUST be written and shown failing BEFORE the fix
appears in your output. Reordering for narrative flow fails the audit even
when the underlying work was correct.

Tools Quick Reference

See references/tools.md for detailed configuration.

Optimization Workflow

1. Measure baseline — record current timing
2. Write regression spec — assert query count
3. Identify bottleneck — use Bullet or rack-mini-profiler
4. Apply fix — eager load, caching, or index
5. Verify — confirm improvement with EXPLAIN ANALYZE
6. Validate — regression spec passes

N+1 Prevention

# Bad
Post.all.each { |p| p.author.name }

# Good
Post.includes(:author).each { |p| p.author.name }

Regression Spec (Query Count Assertion)

Write this spec before applying any optimization to lock in the expected query count:

RSpec.describe "Post index performance" do
  it "loads posts with authors in a fixed number of queries" do
    create_list(:post, 10, :with_author)

    expect do
      Post.includes(:author).to_a
    end.to make_database_queries(count: 2) # posts + authors
  end
end

Use the db-query-matchers gem or a custom make_database_queries matcher. The spec must pass after the fix and fail if a future change reintroduces the N+1.

EXPLAIN ANALYZE Verification

Run directly in rails dbconsole (PostgreSQL) after applying an index or query change:

EXPLAIN ANALYZE
  SELECT posts.*, users.name
  FROM posts
  INNER JOIN users ON users.id = posts.author_id
  WHERE posts.published = true;

Key things to check in the output:

• Seq Scan on large tables → should become Index Scan after adding an index
• actual time rows — confirm the new value is lower than the baseline
• rows estimate accuracy — large discrepancies indicate stale statistics (ANALYZE table_name)

Examples

See EXAMPLES.md for complete examples including:

• N+1 fixes with includes, preload, joins
• Fragment caching and Russian doll caching
• Query optimization with pluck and find_each
• Regression testing with custom matchers

Output Style

Report sections, in the HARD-GATE order:

1. Baseline — timing or query count with source (log line, profiler output, EXPLAIN row).
2. Bottleneck — specific cause + the tool that surfaced it (bullet, rack-mini-profiler, or EXPLAIN ANALYZE — at least one named).
3. Regression spec — RED — spec with make_database_queries(count: <unoptimized>), shown failing.
4. Fix — minimal code change (eager load, index, cache, scope rewrite).
5. Regression spec — GREEN — rerun output at the new count.
6. EXPLAIN ANALYZE — actual output rows for any DB-touching change; call out Seq Scan → Index Scan or actual time delta.
7. Quantified improvement — queries: N → M, p95: X ms → Y ms. Numbers, not adjectives.

Further Reading

• Rails Performance Guide
• Active Record Querying
• rack-mini-profiler
• Bullet gem