debug-rails_skill

Overview

This skill systematically diagnoses and resolves Ruby on Rails application errors. It focuses on common failure patterns—ActiveRecord issues, routing, view and asset problems, N+1 queries, migrations, CSRF and gem conflicts—while recommending modern debugging tools and workflows. Use it to find root causes quickly and verify robust fixes.

How this skill works

The skill guides you through four phases: reproduce and isolate the problem, gather relevant data (logs, stack traces, DB state), form and test hypotheses with breakpoints and console checks, then implement and verify fixes with tests and environment checks. It includes targeted diagnostics and concrete remedies for each common Rails error class, plus commands and gem recommendations for interactive debugging and performance detection.

When to use it

• When ActiveRecord::RecordNotFound occurs or records are unexpectedly absent
• When routes return 404 or route helpers seem broken
• When you see NoMethodError for nil or view template errors during rendering
• When Bullet or logs show N+1 queries and slow pages
• When migrations fail or schema/version mismatches appear
• When assets are missing in production or CSRF token errors surface

Best practices

• Reproduce the bug consistently and capture exact steps before changing code
• Collect full stack trace, request params, session and DB state before guessing
• Use modern debuggers (debug, pry) and Bullet in development to detect issues early
• Write a failing test that reproduces the bug, then implement the fix and run it across environments
• Prefer safe lookup patterns (find_by, safe navigation) and eager loading (includes/preload) where appropriate
• Lock gem versions, check bundle dependency trees, and run migrations in CI-like environments

Example use cases

• Handle a missing User record by switching find to find_by and rendering a 404 page
• Resolve N+1 queries on an index view by adding includes(:association) and verifying with Bullet
• Fix a routing error by running rails routes, adding a missing resource or correcting namespace scope
• Diagnose Asset Pipeline failures by running rails assets:precompile and checking public/assets manifest
• Recover a stuck migration by removing the problematic schema_migration row and re-running migrations after fixes