rails-upgrade

Category: Data & AI | Uploader: ombulabs | Downloads: 0 | Version: v1.0（Latest）
Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, or querying version-specific changes. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.
Changelog: Source: GitHub https://github.com/ombulabs/claude-code_rails-upgrade-skill
Directory Structure

Current level: rails-upgrade/
📁 detection-scripts/
- 📁 patterns/
  - 📄 rails-60-patterns.yml 4.1 KB
  - 📄 rails-70-patterns.yml 4.7 KB
  - 📄 rails-72-patterns.yml 4.1 KB
  - 📄 rails-80-patterns.yml 4.8 KB
  - 📄 rails-81-patterns.yml 3.3 KB
- 📁 templates/
  - 📄 detection-script-template.sh 8.2 KB
📁 examples/
- 📄 detection-script-only.md 10.3 KB
- 📄 multi-hop-upgrade.md 5.9 KB
- 📄 simple-upgrade.md 10.1 KB
📁 reference/
- 📄 breaking-changes-by-version.md 3.9 KB
- 📄 deprecation-warnings.md 8.4 KB
- 📄 dual-boot-strategy.md 9.3 KB
- 📄 gem-compatibility.md 5.6 KB
- 📄 multi-hop-strategy.md 5.4 KB
- 📄 staying-current.md 7.8 KB
- 📄 testing-checklist.md 6.2 KB
📁 templates/
- 📄 app-update-preview-template.md 4.3 KB
- 📄 upgrade-report-template.md 3.7 KB
📁 version-guides/
- 📄 upgrade-3.2-to-4.0.md 6.5 KB
- 📄 upgrade-4.2-to-5.0.md 6.7 KB
- 📄 upgrade-5.0-to-5.1.md 5.3 KB
- 📄 upgrade-5.1-to-5.2.md 6.5 KB
- 📄 upgrade-5.2-to-6.0.md 5.9 KB
- 📄 upgrade-6.0-to-6.1.md 6.0 KB
- 📄 upgrade-6.1-to-7.0.md 7.3 KB
- 📄 upgrade-7.0-to-7.1.md 7.2 KB
- 📄 upgrade-7.1-to-7.2.md 8.1 KB
- 📄 upgrade-7.2-to-8.0.md 8.5 KB
- 📄 upgrade-8.0-to-8.1.md 5.9 KB
📁 workflows/
- 📄 app-update-preview-workflow.md 6.5 KB
- 📄 detection-script-workflow.md 10.3 KB
- 📄 direct-detection-workflow.md 6.4 KB
- 📄 load-defaults-verification-workflow.md 12.7 KB
- 📄 test-suite-verification-workflow.md 8.5 KB
- 📄 upgrade-report-workflow.md 6.9 KB
📄 SKILL.md 23.6 KB
SKILL.md

---
name: rails-upgrade
description: Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 2.3 through 8.1. Use when upgrading Rails applications, planning multi-hop upgrades, or querying version-specific changes. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.
---

# Rails Upgrade Assistant Skill v2.0

## Skill Identity
- **Name:** Rails Upgrade Assistant
- **Version:** 3.0
- **Purpose:** Intelligent Rails application upgrades from 2.3 through 8.1
- **Based on:** Official Rails CHANGELOGs, FastRuby.io methodology, and the FastRuby.io ebook
- **Upgrade Strategy:** Sequential only (no version skipping)

---

## Core Methodology (FastRuby.io Approach)

This skill follows the proven FastRuby.io upgrade methodology:

1. **Incremental Upgrades** - Always upgrade one minor/major version at a time
2. **Assessment First** - Understand scope before making changes
3. **Dual-Boot Testing** - Test both versions during transition using `next_rails` gem
4. **Test Coverage** - Ensure adequate test coverage before upgrading (aim for 80%+)
5. **Gem Compatibility** - Check gem compatibility at each step using RailsBump
6. **Deprecation Warnings** - Address deprecations before upgrading
7. **Backwards Compatible Changes** - Deploy small changes to production before version bump

**Key Resources:**
- See `reference/dual-boot-strategy.md` for dual-boot setup with `next_rails`
- See `reference/deprecation-warnings.md` for managing deprecations
- See `reference/staying-current.md` for maintaining upgrades over time

---

## CRITICAL: Dual-Boot Code Pattern with `NextRails.next?`

### Always Use `NextRails.next?` — Never Use `respond_to?`

When proposing code fixes that must work with both the current and target Rails versions (dual-boot), **always use `NextRails.next?` from the `next_rails` gem** instead of `respond_to?` or other feature-detection patterns.

**Why `respond_to?` is problematic:**
- It is **hard to understand**: a reader must know which Rails version added or removed the method to understand what the branch is really about
- It is **hard to maintain**: `respond_to?` checks accumulate over time and become impossible to clean up because their intent ("which Rails version is this for?") is lost
- It is **fragile**: it couples code to framework implementation details and may produce false positives (e.g., a method exists but behaves differently) or false negatives (e.g., a gem monkey-patches the method in)
- It **obscures intent**: the code does not communicate *why* there are two paths — only that some method may or may not exist

**Why `NextRails.next?` is better:**
- It is **explicit and readable**: anyone reading the code immediately understands "this branch is for the next Rails version"
- It is **easy to clean up**: after the upgrade, search for `NextRails.next?` and remove all branches, keeping only the new-version code
- It is **the standard**: it is the established dual-boot mechanism in the FastRuby.io methodology

### Pattern: Use `NextRails.next?` for Version-Dependent Code

❌ **WRONG — Do NOT use `respond_to?`:**
```ruby
# BAD: Hard to understand, hard to maintain, intent is unclear
if config.respond_to?(:fixture_paths=)
  config.fixture_paths = ["#{::Rails.root}/spec/fixtures"]
else
  config.fixture_path = "#{::Rails.root}/spec/fixtures"
end
```

✅ **CORRECT — Use `NextRails.next?`:**
```ruby
# GOOD: Explicit dual-boot branching — clear intent, easy to clean up later
if NextRails.next?
  config.fixture_paths = ["#{::Rails.root}/spec/fixtures"]
else
  config.fixture_path = "#{::Rails.root}/spec/fixtures"
end
```

### When to Apply This Pattern

Use `NextRails.next?` branching whenever a breaking change requires different code for the current vs. target Rails version, including but not limited to:

- **Configuration changes** (e.g., `fixture_path` → `fixture_paths`, `config.secrets` → `config.credentials`)
- **API changes** (e.g., method renames, changed signatures, removed methods)
- **Gem version differences** (e.g., different gem APIs across Rails versions)
- **Initializer changes** (e.g., different middleware, different default settings)

### Prerequisites

Before using `NextRails.next?` in code, ensure the project has `next_rails` set up:

1. `next_rails` gem is in the Gemfile
2. `Gemfile.next` symlink exists (created by `next --init`)
3. The `NextRails.next?` method is available via the gem

If `next_rails` is NOT set up, **recommend setting it up first** before proposing any dual-boot code changes. See `reference/dual-boot-strategy.md`.

### After Upgrade Completes

Once the upgrade is finalized and the old Rails version is dropped:
- Remove all `if NextRails.next?` / `else` branches
- Keep only the `NextRails.next?` (new version) code path
- Remove the `next_rails` gem from the Gemfile if no longer needed
- This cleanup is part of the post-upgrade checklist

---

## Core Workflow (4-Step Process)

### Step 1: Run Test Suite (MANDATORY FIRST STEP)
- **CRITICAL:** Before any upgrade work begins, run the existing test suite
- Claude executes `bundle exec rspec` or `bundle exec rails test` to verify baseline
- All tests MUST pass before proceeding with any upgrade
- If tests fail, stop and help user fix failing tests first
- Record test count and coverage as baseline metrics
- See `workflows/test-suite-verification-workflow.md` for details

### Step 2: Verify load_defaults Matches Current Rails Version
- **CRITICAL:** Check if `load_defaults` in `config/application.rb` matches the current Rails gem version
- If `load_defaults` is BEHIND the current Rails version:
  - **ASK USER** if they want to update `load_defaults` first
  - **RECOMMEND** updating `load_defaults` to match current Rails before upgrading to next version
  - Generate a `load_defaults` update report showing what changes
  - Run tests again after updating `load_defaults` to verify nothing breaks
- If `load_defaults` matches current Rails version → Proceed to Step 3
- See `workflows/load-defaults-verification-workflow.md` for details

### Step 3: Run Breaking Changes Detection (DIRECT)
- **Claude runs detection checks directly** using Grep, Glob, and Read tools
- No script generation - Claude searches the codebase in real-time
- Finds issues with file:line references
- Collects all findings immediately
- See `workflows/direct-detection-workflow.md` for patterns to search

### Step 4: Generate Reports Based on Findings
- **Comprehensive Upgrade Report**: Breaking changes analysis with OLD vs NEW code examples, custom code warnings with ⚠️ flags, step-by-step migration plan, testing checklist and rollback plan
- **app:update Preview Report**: Shows exact configuration file changes (OLD vs NEW), lists new files to be created, impact assessment (HIGH/MEDIUM/LOW)

---

## Trigger Patterns

Claude should activate this skill when user says:

**Upgrade Requests:**
- "Upgrade my Rails app to [version]"
- "Help me upgrade from Rails [x] to [y]"
- "What breaking changes are in Rails [version]?"
- "Plan my upgrade from [x] to [y]"
- "What Rails version am I using?"
- "Analyze my Rails app for upgrade"
- "Find breaking changes in my code"
- "Check my app for Rails [version] compatibility"

**Specific Report Requests:**
- "Show me the app:update changes"
- "Preview configuration changes for Rails [version]"
- "Generate the upgrade report"
- "What will change if I upgrade?"

---

## CRITICAL: Sequential Upgrade Strategy

### ⚠️ Version Skipping is NOT Allowed

Rails upgrades MUST follow a sequential path. Examples:

**For Rails 5.x to 8.x:**
```
5.0.x → 5.1.x → 5.2.x → 6.0.x → 6.1.x → 7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x
```

**You CANNOT skip versions.** Examples:
- ❌ 5.2 → 6.1 (skips 6.0)
- ❌ 6.0 → 7.0 (skips 6.1)
- ❌ 7.0 → 8.0 (skips 7.1 and 7.2)
- ✅ 5.2 → 6.0 (correct)
- ✅ 7.0 → 7.1 (correct)
- ✅ 7.2 → 8.0 (correct)

If user requests a multi-hop upgrade (e.g., 5.2 → 8.1):
1. Explain the sequential requirement
2. Break it into individual hops
3. Generate separate reports for each hop
4. Recommend completing each hop fully before moving to next

---

## Supported Upgrade Paths

### Legacy Rails (2.3 - 4.2)

| From | To | Difficulty | Key Changes | Ruby Required |
|------|-----|-----------|-------------|---------------|
| 2.3.x | 3.0.x | Very Hard | XSS protection, routes syntax | 1.8.7 - 1.9.3 |
| 3.0.x | 3.1.x | Medium | Asset pipeline, jQuery | 1.8.7 - 1.9.3 |
| 3.1.x | 3.2.x | Easy | Ruby 1.9.3 support | 1.8.7 - 2.0 |
| 3.2.x | 4.0.x | Hard | Strong Parameters, Turbolinks | 1.9.3+ |
| 4.0.x | 4.1.x | Medium | Spring, secrets.yml | 1.9.3+ |
| 4.1.x | 4.2.x | Medium | ActiveJob, Web Console | 1.9.3+ |
| 4.2.x | 5.0.x | Hard | ActionCable, API mode, ApplicationRecord | 2.2.2+ |

### Modern Rails (5.0 - 8.1)

| From | To | Difficulty | Key Changes | Ruby Required |
|------|-----|-----------|-------------|---------------|
| 5.0.x | 5.1.x | Easy | Encrypted secrets, yarn default | 2.2.2+ |
| 5.1.x | 5.2.x | Medium | Active Storage, credentials | 2.2.2+ |
| 5.2.x | 6.0.x | Hard | Zeitwerk, Action Mailbox/Text | 2.5.0+ |
| 6.0.x | 6.1.x | Medium | Horizontal sharding, strict loading | 2.5.0+ |
| 6.1.x | 7.0.x | Hard | Hotwire/Turbo, Import Maps | 2.7.0+ |
| 7.0.x | 7.1.x | Medium | Composite keys, async queries | 2.7.0+ |
| 7.1.x | 7.2.x | Medium | Transaction-aware jobs, DevContainers | 3.1.0+ |
| 7.2.x | 8.0.x | Very Hard | Propshaft, Solid gems, Kamal | 3.2.0+ |
| 8.0.x | 8.1.x | Easy | Bundler-audit, max_connections | 3.2.0+ |

---

## Available Resources

### Core Documentation
- `SKILL.md` - This file (entry point)

### Version-Specific Guides (Load as needed)

**Legacy Rails:**
- `version-guides/upgrade-3.2-to-4.0.md` - Rails 3.2 → 4.0 (Strong Parameters)
- `version-guides/upgrade-4.2-to-5.0.md` - Rails 4.2 → 5.0 (ApplicationRecord)

**Modern Rails:**
- `version-guides/upgrade-5.0-to-5.1.md` - Rails 5.0 → 5.1 (Encrypted secrets)
- `version-guides/upgrade-5.1-to-5.2.md` - Rails 5.1 → 5.2 (Active Storage, Credentials)
- `version-guides/upgrade-5.2-to-6.0.md` - Rails 5.2 → 6.0 (Zeitwerk)
- `version-guides/upgrade-6.0-to-6.1.md` - Rails 6.0 → 6.1 (Horizontal sharding)
- `version-guides/upgrade-6.1-to-7.0.md` - Rails 6.1 → 7.0 (Hotwire/Turbo)
- `version-guides/upgrade-7.0-to-7.1.md` - Rails 7.0 → 7.1 (Composite keys)
- `version-guides/upgrade-7.1-to-7.2.md` - Rails 7.1 → 7.2 (Transaction jobs)
- `version-guides/upgrade-7.2-to-8.0.md` - Rails 7.2 → 8.0 (Propshaft)
- `version-guides/upgrade-8.0-to-8.1.md` - Rails 8.0 → 8.1 (bundler-audit)

### Workflow Guides (Load when generating deliverables)
- `workflows/test-suite-verification-workflow.md` - **MANDATORY FIRST STEP** - How to run and verify test suite
- `workflows/load-defaults-verification-workflow.md` - **MANDATORY SECOND STEP** - Verify load_defaults matches Rails version
- `workflows/direct-detection-workflow.md` - How to run breaking change detection directly
- `workflows/upgrade-report-workflow.md` - How to generate upgrade reports
- `workflows/app-update-preview-workflow.md` - How to generate app:update previews

### Examples (Load when user needs clarification)
- `examples/simple-upgrade.md` - Single-hop upgrade example
- `examples/multi-hop-upgrade.md` - Multi-hop upgrade example

### Reference Materials
- `reference/dual-boot-strategy.md` - Dual-boot with next_rails gem
- `reference/deprecation-warnings.md` - Finding and fixing deprecations
- `reference/staying-current.md` - Keeping up with Rails releases
- `reference/breaking-changes-by-version.md` - Quick lookup
- `reference/multi-hop-strategy.md` - Multi-version planning
- `reference/testing-checklist.md` - Comprehensive testing
- `reference/gem-compatibility.md` - Common gem version requirements

### Detection Pattern Resources
- `detection-scripts/patterns/rails-*.yml` - Version-specific patterns for direct detection

### Report Templates
- `templates/upgrade-report-template.md` - Main upgrade report structure
- `templates/app-update-preview-template.md` - Configuration preview

---

## High-Level Workflow

When user requests an upgrade, follow this workflow:

### Step 1: Run Test Suite (MANDATORY FIRST STEP)
```
⚠️  THIS STEP IS REQUIRED BEFORE ANY OTHER WORK

1. Read: workflows/test-suite-verification-workflow.md
2. Detect test framework (RSpec, Minitest, or both)
3. Run test suite with: bundle exec rspec OR bundle exec rails test
4. Capture results: total tests, passing, failing, pending
5. If ANY tests fail:
   - STOP the upgrade process
   - Report failing tests to user
   - Offer to help fix failing tests
   - Do NOT proceed until all tests pass
6. If all tests pass:
   - Record baseline metrics (test count, coverage if available)
   - Proceed to Step 2
```

### Step 2: Detect Current Version & Verify load_defaults
```
1. Read Gemfile to find current Rails gem version
2. Read config/application.rb for load_defaults version
3. Store: rails_gem_version, load_defaults_version, target_version
4. Compare rails_gem_version with load_defaults_version
```

### Step 3: Check load_defaults Alignment (BLOCKING STEP)
```
⚠️  THIS STEP MAY BLOCK THE UPGRADE

1. Read: workflows/load-defaults-verification-workflow.md
2. If load_defaults_version < rails_gem_version (e.g., load_defaults 7.0 on Rails 7.2):
   - STOP and inform user of mismatch
   - Explain: "Your app is on Rails X.Y but using load_defaults X.Z"
   - RECOMMEND: "Update load_defaults to X.Y before upgrading to next version"
   - ASK USER: "Would you like to update load_defaults to X.Y first?"
   - If YES → Generate load_defaults update report, help update, re-run tests
   - If NO → Warn about risks and proceed (user's choice)
3. If load_defaults_version == rails_gem_version:
   - Proceed to Step 4
```

### Step 4: Validate Upgrade Path
```
1. Check if upgrade is single-hop or multi-hop
2. If multi-hop, explain sequential requirement
3. Plan individual hops
```

### Step 5: Run Breaking Changes Detection (DIRECT)
```
Claude runs detection directly using tools - NO script generation needed

1. Read: workflows/direct-detection-workflow.md
2. Read: detection-scripts/patterns/rails-{VERSION}-patterns.yml
3. For each pattern in the patterns file:
   - Use Grep tool to search for the pattern
   - Collect file paths and line numbers
   - Store findings with context
4. Read: version-guides/upgrade-{FROM}-to-{TO}.md for context
5. Compile all findings into structured data
```

### Step 6: Load Report Resources & Generate Reports
```
1. Read: templates/upgrade-report-template.md
2. Read: templates/app-update-preview-template.md
3. Read: workflows/upgrade-report-workflow.md
4. Read: workflows/app-update-preview-workflow.md
```

**Deliverable #1: Comprehensive Upgrade Report**
- **Input:** Direct detection findings + version guide data
- **Output:** Report with real code examples from user's project

**Deliverable #2: app:update Preview**
- **Input:** Actual config files + findings
- **Output:** Preview with real file paths and changes

### Step 7: Present Reports & Offer Help
```
1. Present Comprehensive Upgrade Report first
2. Present app:update Preview Report second
3. Explain next steps
4. Offer to help implement changes
```

---

## Pre-Upgrade Checklist (FastRuby.io Best Practices)

Before starting ANY upgrade:

### 1. Test Coverage Assessment (AUTOMATED - Step 1 of Workflow)
- [x] Run test suite - all tests passing? **← Claude runs this automatically**
- [x] Check test coverage (aim for >70%) **← Claude captures this if SimpleCov is configured**
- [ ] Review critical paths have coverage

**Note:** This step is now automated. Claude will run the test suite and BLOCK the upgrade if any tests fail.

### 2. Dependency Audit
- [ ] Run `bundle outdated`
- [ ] Check gem compatibility with target Rails version
- [ ] Identify gems that need upgrading first

### 3. Database Backup
- [ ] Backup production database
- [ ] Backup development/staging databases
- [ ] Verify backup restore process works

### 4. Git Branch Strategy
- [ ] Create upgrade branch from main/master
- [ ] Set up CI for upgrade branch
- [ ] Plan merge strategy

### 5. Deprecation Warnings
- [ ] Run app with `RAILS_DEPRECATION_WARNINGS=1`
- [ ] Address existing deprecation warnings
- [ ] Enable verbose deprecations in test environment

---

## Common Request Patterns

### Pattern 1: Full Upgrade Request
**User says:** "Upgrade my Rails app to 8.1"

**Action - Step 1 (MANDATORY: Verify Tests Pass):**
1. Load: `workflows/test-suite-verification-workflow.md`
2. Detect test framework (RSpec or Minitest)
3. Run test suite: `bundle exec rspec` or `bundle exec rails test`
4. If tests FAIL → STOP and help fix tests first
5. If tests PASS → Record baseline and proceed

**Action - Step 2 (MANDATORY: Verify load_defaults):**
1. Load: `workflows/load-defaults-verification-workflow.md`
2. Read Gemfile.lock for current Rails gem version
3. Read config/application.rb for load_defaults version
4. If load_defaults < Rails gem version:
   - INFORM user: "Your app uses Rails X.Y but load_defaults is set to X.Z"
   - RECOMMEND: "Update load_defaults to X.Y before upgrading to the next version"
   - ASK: "Would you like to update load_defaults to X.Y first? (Recommended)"
   - If YES → Help update load_defaults, re-run tests, then proceed
   - If NO → Warn about risks, proceed with upgrade
5. If load_defaults matches → Proceed to Step 3

**Action - Step 3 (Run Detection Directly):**
1. Validate upgrade path
2. Load: `workflows/direct-detection-workflow.md`
3. Load: `detection-scripts/patterns/rails-{VERSION}-patterns.yml`
4. Use Grep/Glob/Read tools to search for each pattern
5. Collect findings with file:line references

**Action - Step 4 (Generate Reports):**
1. Load: `workflows/upgrade-report-workflow.md`
2. Load: `workflows/app-update-preview-workflow.md`
3. Generate Comprehensive Upgrade Report (using direct findings)
4. Generate app:update Preview (using actual config files)
5. Present both reports to user
6. Offer to help implement changes

### Pattern 2: Multi-Hop Request
**User says:** "Help me upgrade from Rails 5.2 to 8.1"

**Action - Step 1 (MANDATORY: Verify Tests Pass):**
1. Run test suite BEFORE planning any upgrade work
2. If tests fail → STOP and fix first
3. If tests pass → Proceed with planning

**Action - Step 2 (MANDATORY: Verify load_defaults):**
1. Check if load_defaults matches current Rails version
2. If mismatched → Recommend updating load_defaults FIRST
3. For multi-hop: Ensure load_defaults is current before starting

**Action - Step 3 (Plan & Execute):**
1. Explain sequential requirement
2. Calculate hops: 5.2 → 6.0 → 6.1 → 7.0 → 7.1 → 7.2 → 8.0 → 8.1
3. Reference: `reference/multi-hop-strategy.md`
4. Follow Pattern 1 for FIRST hop (5.2 → 6.0)
5. After first hop complete, repeat for next hops
6. **IMPORTANT:** After each hop, ensure load_defaults is updated before next hop

### Pattern 3: Breaking Changes Analysis Only
**User says:** "What breaking changes affect my app for Rails 8.0?"

**Action - Step 1 (MANDATORY: Verify Tests Pass):**
1. Run test suite first
2. If tests fail → Warn user and recommend fixing first
3. If tests pass → Proceed with analysis

**Action - Step 2 (MANDATORY: Verify load_defaults):**
1. Check load_defaults alignment
2. If mismatched → Recommend updating first

**Action - Step 3 (Run Detection):**
1. Load: `workflows/direct-detection-workflow.md`
2. Run detection directly using tools
3. Present findings summary
4. Offer to generate full upgrade report

---

## Quality Checklist

Before delivering, verify:

**For Direct Detection:**
- [ ] All patterns from version-specific YAML file checked
- [ ] Grep/Glob tools used correctly for each pattern
- [ ] File:line references collected for all findings
- [ ] Context captured for each finding

**For Comprehensive Upgrade Report:**
- [ ] All {PLACEHOLDERS} replaced with actual values
- [ ] Used ACTUAL findings from direct detection (not generic examples)
- [ ] Breaking changes section includes real file:line references
- [ ] Custom code warnings based on actual detected issues
- [ ] Code examples use user's actual code from affected files
- [ ] Next steps clearly outlined

**For app:update Preview:**
- [ ] All {PLACEHOLDERS} replaced with actual values
- [ ] File list matches user's actual config files
- [ ] Diffs based on real current config vs target version
- [ ] Next steps clearly outlined

---

## Key Principles

1. **ALWAYS Run Test Suite First** (MANDATORY - no exceptions, no upgrade work until tests pass)
2. **Block on Failing Tests** (if tests fail, STOP and help fix them before any upgrade work)
3. **ALWAYS Verify load_defaults** (MANDATORY - check if load_defaults matches current Rails version)
4. **Recommend Updating load_defaults First** (if behind current Rails, update load_defaults BEFORE upgrading to next version)
5. **Run Detection Directly** (use Grep/Glob/Read tools - no script generation needed)
6. **Always Use Actual Findings** (no generic examples in reports)
7. **Always Flag Custom Code** (with ⚠️ warnings based on detected issues)
8. **Always Use Templates** (for consistency)
9. **Always Check Quality** (before delivery)
10. **Load Workflows as Needed** (don't hold everything in memory)
11. **Sequential Process is Critical** (tests → load_defaults check → detection → reports)
12. **Follow FastRuby.io Methodology** (incremental upgrades, assessment first)
13. **Always Use `NextRails.next?` for Dual-Boot Code** (NEVER use `respond_to?` for version branching — it is hard to understand, hard to maintain, and obscures intent. Use `NextRails.next?` from the `next_rails` gem instead. See "Dual-Boot Code Pattern" section above.)

---

## Success Criteria

A successful upgrade assistance session:

✅ **Ran test suite FIRST** (Step 1 - MANDATORY)
✅ **Verified all tests pass** (blocked if tests failed)
✅ **Recorded baseline metrics** (test count, coverage)
✅ **Checked load_defaults alignment** (Step 2 - MANDATORY)
✅ **Recommended load_defaults update if behind** (asked user before proceeding)
✅ **Updated load_defaults if user agreed** (re-ran tests after update)
✅ **Ran detection directly** (using Grep/Glob/Read tools - no script)
✅ **Generated Comprehensive Upgrade Report** using actual findings
✅ **Generated app:update Preview** using actual config files
✅ Used user's actual code from findings (not generic examples)
✅ Flagged all custom code with ⚠️ warnings based on detected issues
✅ Provided clear next steps
✅ Offered to help implement changes

---

**Version:** 3.0
**Last Updated:** January 2025
**Skill Type:** Modular with external workflows and examples
**Methodology:** Based on FastRuby.io upgrade best practices and "The Complete Guide to Upgrade Rails" ebook
**Attribution:** Content based on "The Complete Guide to Upgrade Rails" by FastRuby.io (OmbuLabs)

**v3.0 Changes:**
- **MAJOR:** Removed script generation - Claude now runs detection directly using tools
- Detection uses Grep, Glob, and Read tools instead of generating bash scripts
- Eliminated user round-trip (no more "run this script and share results")
- Streamlined from 5-step to 4-step process
- New workflow file: `workflows/direct-detection-workflow.md`
- Removed: `workflows/detection-script-workflow.md`, `examples/detection-script-only.md`

**v2.2 Changes:**
- Added mandatory `load_defaults` verification as Step 2 of all upgrade workflows
- If `load_defaults` is behind current Rails version, skill now:
  - Informs user of the mismatch
  - Recommends updating `load_defaults` to match current Rails BEFORE upgrading to next version
  - Asks user for confirmation before proceeding
- New workflow file: `workflows/load-defaults-verification-workflow.md`

**v2.1 Changes:**
- Added mandatory test suite verification as Step 1 of all upgrade workflows
- Upgrade process now BLOCKS if any tests fail
- New workflow file: `workflows/test-suite-verification-workflow.md`
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
rails-upgrade

Directory Structure

SKILL.md

Report

Notice
