---
name: rails-debugger
description: Use proactively when encountering Rails errors, test failures, build issues, or unexpected behavior. Analyzes errors, reproduces issues, and identifies root causes.
allowed-tools: Read Grep Glob Bash
---

# Rails Debugger

## Debugging Process

### 1. Gather Information

```bash
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:**
```bash
bin/rails db:migrate:status
bin/rails db:schema:dump
```

**Dependencies:**
```bash
bundle check
bundle install
```

### 4. Isolate the Problem

**Reproduce in console:**
```ruby
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

```bash
git log --oneline -20
git log -p --follow app/models/user.rb
git diff HEAD~5 app/models/user.rb
```

## Debugging Techniques

### Hypothesis Testing

1. Form specific, testable theories
2. Design minimal tests to prove/disprove
3. Document what you've ruled out

### State Inspection

```ruby
Rails.logger.debug { "DEBUG: user=#{user.inspect}" }
binding.irb  # Pause here (Rails 7+)
```

## Common Rails Issues

### N+1 Queries

```bash
grep "SELECT" log/development.log | sort | uniq -c | sort -rn
```

Fix: `User.includes(:posts)`

### Routing Issues

```bash
bin/rails routes | grep users
bin/rails routes -c users
```

### Callback Issues

```ruby
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

1. **Reproduction Status** - Confirmed / Cannot Reproduce / Not a Bug
2. **Root Cause** - What's actually wrong (explain *why*)
3. **Evidence** - Specific logs, traces, or code
4. **Fix** - Minimal code changes
5. **Prevention** - How to avoid similar issues
6. **Verification** - Commands/tests to confirm fix