About rails-debugger
rails-debugger is a Rails debugging skill for developers investigating application errors. It guides log and stack-trace analysis, issue isolation, bug classification, and reporting a minimal fix with verification steps.
Key features
- 01Log and stack-trace analysis
- 02Database and dependency checks
- 03Console reproduction and binary search
- 04Recent-change inspection
- 05Structured bug report with verification
Use cases
- 01Trace an exception to its application origin
- 02Investigate migration or dependency problems
- 03Reproduce and classify a reported bug
Install
Copy the command and run it in a terminal.
$
npx skills add https:/After installing, type/rails-debuggerin Claude Code to confirm it loaded.
Details
From the project READMERails Debugger
Debugging Process
1. Gather Information
tail -100 log/development.log
bundle exec rspec --format documentation
bin/rails db:migrate:status
2. Analyze Stack Traces
Identify the origin:
- Find the first line in
app/directory - Note the file, line number, and method
Common patterns:
| Error | Likely Cause |
|---|---|
NoMethodError: undefined method for nil:NilClass | Missing association, nil return |
ActiveRecord::RecordNotFound | ID doesn't exist, scoping issue |
ActiveRecord::RecordInvalid | Validation failed |
ActionController::ParameterMissing | Required param not sent |
NameError: uninitialized constant | Missing require, typo |
LoadError | File not found, autoload path issue |
3. Check Common Issues
Database:
bin/rails db:migrate:status
bin/rails db:schema:dump
Dependencies:
bundle check
bundle install
4. Isolate the Problem
Reproduce in console:
user = User.find(123)
user.some_method # Does it fail here?
Binary search:
- Comment out half the code
- Does error persist?
- Narrow down
5. Check Recent Changes
git log --oneline -20
git log -p --follow app/models/user.rb
git diff HEAD~5 app/models/user.rb
Debugging Techniques
Hypothesis Testing
- Form specific, testable theories
- Design minimal tests to prove/disprove
- Document what you've ruled out
State Inspection
Rails.logger.debug { "DEBUG: user=#{user.inspect}" }
binding.irb # Pause here (Rails 7+)
Common Rails Issues
N+1 Queries
grep "SELECT" log/development.log | sort | uniq -c | sort -rn
Fix: User.includes(:posts)
Routing Issues
bin/rails routes | grep users
bin/rails routes -c users
Callback Issues
User._create_callbacks.map(&:filter)
User._save_callbacks.map(&:filter)
Bug Report Validation
Classification
| Status | Meaning |
|---|---|
| Confirmed Bug | Reproduced with clear deviation |
| Cannot Reproduce | Unable to reproduce |
| Not a Bug | Behavior is correct per spec |
| Data Issue | Problem with specific data |
Output Format
- Reproduction Status - Confirmed / Cannot Reproduce / Not a Bug
- Root Cause - What's actually wrong (explain why)
- Evidence - Specific logs, traces, or code
- Fix - Minimal code changes
- Prevention - How to avoid similar issues
- Verification - Commands/tests to confirm fix
Comments
Markdown supported