Rails Upgrade Assistant Skill

Skill Identity

• Name: Rails Upgrade Assistant
• Purpose: Intelligent Rails application upgrades from 2.3 through 8.1
• Skill Type: Modular with external workflows and examples
• Upgrade Strategy: Sequential only (no version skipping)
• 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)

Dependencies

• rails-load-defaults skill (github.com/ombulabs/claude-code_rails-load-defaults-skill) — Handles incremental

  load_defaults

  updates with tiered risk assessment (Tier 1: low-risk, Tier 2: needs codebase grep, Tier 3: requires human review). Must be installed for Step 2 of the upgrade workflow.
• dual-boot skill (github.com/ombulabs/claude-code_dual-boot-skill) — Sets up and manages dual-boot environments using the

  next_rails

  gem. Covers setup,

  NextRails.next?

  code patterns, CI configuration, and post-upgrade cleanup. Must be installed for Step 4 of the upgrade workflow.

Core Methodology (FastRuby.io Approach)

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

• DELEGATE to the

  dual-boot

  skill for dual-boot setup with

  next_rails

  (see Dependencies)
• 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?

NextRails.next?

next_rails

respond_to?

dual-boot

• Setup and initialization (

  next_rails --init

  ,

  Gemfile.next

  )

• NextRails.next?

  code patterns and examples
• CI configuration for dual-boot testing
• Post-upgrade cleanup (removing dual-boot branches)

Core Workflow (5-Step Process)

Step 0: Verify Latest Patch Version (MANDATORY PRE-STEP)

• CRITICAL: Before any upgrade work begins, verify the app is on the latest patch release of its current Rails series
• Read

  Gemfile.lock

  to find the exact current Rails version (e.g.,

  3.2.19

  )
• Compare against the latest patch for that series:
  • EOL series (≤ 6.1): Use the static table in

    reference/multi-hop-strategy.md

  • Active series (≥ 7.0): Query the RubyGems API at runtime (see

    reference/multi-hop-strategy.md

    for commands)
• If the app is NOT on the latest patch:
  • Inform user: "Your app is on Rails X.Y.Z but the latest patch is X.Y.W — you should upgrade to the latest patch first"
  • Guide user through updating the Gemfile and running

    bundle update rails

  • Run test suite after patch upgrade to verify nothing broke
  • Deploy patch upgrade before proceeding with the minor/major version hop
• If the app IS on the latest patch → Proceed to Step 1
• Why: Patch releases contain security fixes, bug fixes, and additional deprecation warnings that make the next version hop safer and easier to debug

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
• DELEGATE to the

  rails-load-defaults

  skill for detection and incremental update
• That skill handles tiered, per-config updates with test runs between each change
• If

  load_defaults

  matches current Rails version → Proceed to Step 3
• DEPENDENCY: Requires the rails-load-defaults skill

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

• "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"

• "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

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

• ❌ 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)

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)

Modern Rails (5.0 - 8.1)

Available Resources

Core Documentation

• SKILL.md

  - This file (entry point)

Version-Specific Guides (Load as needed)

• 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)

• 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
• EXTERNAL DEPENDENCY:

  rails-load-defaults

  skill - MANDATORY SECOND STEP - Verify and update load_defaults to match Rails version (https://github.com/ombulabs/claude-code_rails-load-defaults-skill)

• 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

• EXTERNAL DEPENDENCY:

  dual-boot

  skill - Dual-boot setup and management with next_rails (https://github.com/ombulabs/claude-code_dual-boot-skill)

• 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

Step 0: Verify Latest Patch Version (MANDATORY PRE-STEP)

⚠️  THIS STEP IS REQUIRED BEFORE ANY OTHER WORK

1. Read Gemfile.lock to find exact current Rails version (e.g., 3.2.19)
2. Compare against latest patch for that series:
   - EOL series (≤ 6.1): use static table in reference/multi-hop-strategy.md
   - Active series (≥ 7.0): query RubyGems API (see reference/multi-hop-strategy.md for commands)
3. If current version < latest patch:
   - INFORM user: "Your app is on Rails X.Y.Z but the latest patch is X.Y.W"
   - Guide through Gemfile update and bundle update rails
   - Run test suite after patch upgrade
   - Deploy patch upgrade before proceeding
   - Do NOT proceed to next minor/major until on latest patch
4. If current version == latest patch:
   - Proceed to Step 1

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 (BLOCKING STEP)

⚠️  THIS STEP MAY BLOCK THE UPGRADE

1. Read Gemfile to find current Rails gem version
2. Read config/application.rb for load_defaults version
3. Compare rails_gem_version with load_defaults_version
4. If load_defaults_version < rails_gem_version:
   - DELEGATE to the rails-load-defaults skill for incremental update
   - That skill walks through each config change one at a time, grouped by risk tier
   - Tests are re-run between each change
   - Do NOT proceed until load_defaults matches the current Rails version
5. If load_defaults_version == rails_gem_version:
   - Proceed to Step 3

Step 3: Set Up Dual-Boot with next_rails (IF NOT ALREADY SET UP)

DELEGATE to the dual-boot skill for setup and initialization.
That skill handles:
- Checking if Gemfile.next already exists (to avoid duplicate next? method)
- Adding next_rails gem and running next_rails --init
- Installing dependencies for both Rails versions
- Configuring the Gemfile with if next? conditionals

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

• Input: Direct detection findings + version guide data
• Output: Report with real code examples from user's project

• 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)

1. Test Coverage Assessment (AUTOMATED - Step 1 of Workflow)

• Run test suite - all tests passing? ← Claude runs this automatically
• Check test coverage (aim for >70%) ← Claude captures this if SimpleCov is configured
• Review critical paths have coverage

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

1. Read

   Gemfile.lock

   for exact Rails version
2. Compare against latest patch for that series (see

   reference/multi-hop-strategy.md

   )
3. If not on latest patch → Guide user through patch upgrade first
4. If on latest patch → Proceed to Step 1

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

1. Read Gemfile.lock for current Rails gem version
2. Read config/application.rb for load_defaults version
3. If load_defaults < Rails gem version:
   • INFORM user: "Your app uses Rails X.Y but load_defaults is set to X.Z"
   • DELEGATE to the

     rails-load-defaults

     skill for incremental, tiered update
   • That skill handles per-config analysis, test runs, and risk assessment
4. If load_defaults matches → Proceed to Step 3

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

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

1. Check exact current version from

   Gemfile.lock

2. If not on latest patch of current series → Upgrade to latest patch first
3. For multi-hop: This check applies at the START and again after each hop

1. Run test suite BEFORE planning any upgrade work
2. If tests fail → STOP and fix first
3. If tests pass → Proceed with planning

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

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

1. Check if on latest patch — warn if not, recommend patching first

1. Run test suite first
2. If tests fail → Warn user and recommend fixing first
3. If tests pass → Proceed with analysis

1. Check load_defaults alignment
2. If mismatched → Recommend updating first

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

• 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

• 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

• 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 Verify Latest Patch First (MANDATORY - ensure app is on latest patch of current series before any version hop)
2. ALWAYS Run Test Suite (MANDATORY - no exceptions, no upgrade work until tests pass)
3. Block on Failing Tests (if tests fail, STOP and help fix them before any upgrade work)
4. ALWAYS Verify load_defaults (MANDATORY - check if load_defaults matches current Rails version)
5. Recommend Updating load_defaults First (if behind current Rails, update load_defaults BEFORE upgrading to next version)
6. Run Detection Directly (use Grep/Glob/Read tools - no script generation needed)
7. Always Use Actual Findings (no generic examples in reports)
8. Always Flag Custom Code (with ⚠️ warnings based on detected issues)
9. Always Use Templates (for consistency)
10. Always Check Quality (before delivery)
11. Load Workflows as Needed (don't hold everything in memory)
12. Sequential Process is Critical (patch check → tests → load_defaults check → detection → reports)
13. Follow FastRuby.io Methodology (incremental upgrades, assessment first)
14. Always Use

    NextRails.next?

    for Dual-Boot Code (NEVER use

    respond_to?

    for version branching. DELEGATE to the

    dual-boot

    skill for patterns and setup.)

Success Criteria