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.
Installer avec Codex ou Claude Copiez ce prompt, collez-le dans Codex, Claude ou un autre assistant, puis laissez-le vérifier la page du skill et l'installer pour vous.
Une commande directe contourne le prompt de vérification. Examinez la source avant de l'exécuter.
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
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
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 2 of the upgrade workflow.
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). Used as the final step after the Rails version upgrade is complete.
Core Methodology (FastRuby.io Approach)
This skill follows the proven FastRuby.io upgrade methodology:
Incremental Upgrades - Always upgrade one minor/major version at a time
Assessment First - Understand scope before making changes
Dual-Boot Testing - Test both versions during transition using next_rails gem
Test Coverage - Ensure adequate test coverage before upgrading (aim for 80%+)
Gem Compatibility - Check gem compatibility at each step using RailsBump
Deprecation Warnings - Address deprecations before upgrading
Backwards Compatible Changes - Deploy small changes to production before version bump
Key Resources:
DELEGATE to the dual-boot skill for dual-boot setup with next_rails (see Dependencies)
See references/deprecation-warnings.md for managing deprecations
See references/staying-current.md for maintaining upgrades over time
CRITICAL: Dual-Boot Code Pattern with NextRails.next?
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 — never use respond_to? or other feature-detection patterns.
DELEGATE to the dual-boot skill for:
Setup and initialization (next_rails --init, Gemfile.next)
Workflow Guides (Load when generating deliverables)
workflows/test-suite-verification-workflow.md - MANDATORY FIRST STEP - How to run and verify test suite
workflows/direct-detection-workflow.md - How to run breaking change detection directly
workflows/upgrade-report-workflow.md - How to generate upgrade reports
workflows/gem-compatibility-workflow.md - Load in Step 4.5 - Per-lockfile gem compatibility check against the target Rails version. Documents both the primary (next_railsbundle_report compatibility) and the secondary (railsbump.org API) and the rules for when to escalate.
workflows/ci-sync-workflow.md - MANDATORY before opening the upgrade PR - How to verify CI config matches the upgraded Gemfile
workflows/app-update-preview-workflow.md - How to generate app:update previews
upgrade-cleanup companion plugin - User-triggered. Removes dual-boot scaffolding and drops NextRails.next? / NextRails.current? branches. Deprecation triage stays with this skill for the next hop.
Examples (Load when user needs clarification)
examples/simple-upgrade.md - Single-hop upgrade example
examples/multi-hop-upgrade.md - Multi-hop upgrade example
references/gem-compatibility.md - Gem update order and the "no compatible version" playbook (fork / vendor / replace). Load only when Step 4.5's compatibility check produced blockers.
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
When user requests an upgrade, follow this 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 (≤ 7.1): use static table in references/multi-hop-strategy.md
- Active series (≥ 7.2): query RubyGems API (see references/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
Why patch first: Patch releases contain security fixes, bug fixes, and additional deprecation warnings. Starting the version hop on the latest patch is safer (the security fixes are already in production) and easier to debug (the new deprecation warnings surface issues that would otherwise show up mid-upgrade).
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: Set Up Dual-Boot with next_rails (EARLY SETUP)
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 3: 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 4: 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 4.5: Check Gem Compatibility Against Target Rails
Determines which gems must be bumped before the Rails version change can resolve.
1. Read: workflows/gem-compatibility-workflow.md and follow it. The
workflow documents the primary check (next_rails bundle_report),
the conditions for escalating to the secondary (railsbump API),
and the bucket mapping for both.
2. Pass the resulting three buckets — required bumps, blockers,
already compatible — into Step 5's report so the gem-update
section reflects real per-lockfile data.
3. If any blockers exist, load references/gem-compatibility.md for
the fork/replace/vendor playbook and the gem update order. Skip
otherwise.
Input: Direct detection findings + version guide data
Output: A report covering breaking changes (with OLD vs NEW code examples taken from the user's actual files), custom-code warnings flagged with ⚠️, a step-by-step migration plan, a testing checklist, and a rollback plan.
Deliverable #2: app:update Preview
Input: Actual config files + findings
Output: A preview showing exact configuration file changes (OLD vs NEW), a list of new files that will be created, and a per-file impact assessment (HIGH / MEDIUM / LOW).
Step 6: Present Reports & Implement Changes
1. Present Comprehensive Upgrade Report first
2. Present app:update Preview Report second
3. Implement breaking change fixes using `NextRails.next?` for dual-boot code
4. Update Gemfile to target Rails version
5. Run test suite against both versions
6. **Check CI config matches the upgraded Gemfile** — load `workflows/ci-sync-workflow.md`, fix any mismatches before proceeding
7. Deploy and verify
Do not fix deprecations printed by the next version during this hop. Those belong to the next upgrade cycle and will be addressed before the next version bump. Triaging them now expands the scope of the current hop and risks shipping a half-finished change.
Step 7: Align load_defaults
⚠️ THIS STEP HAPPENS AFTER THE UPGRADE IS COMPLETE
1. DELEGATE to the rails-load-defaults skill
2. That skill walks through each config change one at a time, grouped by risk tier
3. Tests are re-run between each change
4. Consolidates into config/application.rb when done
Step 8: Mention Cleanup (USER-TRIGGERED)
⚠️ DO NOT AUTO-RUN. Mention it; let the user decide.
1. Tell the user the cleanup option exists
2. Delegate to the upgrade-cleanup plugin only when the user explicitly asks
("finish the upgrade", "clean up dual-boot", "drop the NextRails branches")
3. The cleanup plugin removes NextRails.next? / NextRails.current? branches
and retires dual-boot scaffolding. Deprecation triage stays with this
skill for the next hop, not with cleanup.
Sample wording the agent can crib from when prompting the user:
Rails X.Y is in. When you're ready to remove dual-boot scaffolding (drop NextRails.next? / NextRails.current? branches, retire Gemfile.next), ask me to clean up. If you're heading straight to the next hop, keeping dual-boot in place is also fine.
Pre-Upgrade Checklist (FastRuby.io Best Practices)
Before starting ANY upgrade:
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
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 deprecations turned on (configured in config/environment files)
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 0 (MANDATORY: Verify Latest Patch):
Read Gemfile.lock for exact Rails version
Compare against latest patch for that series (see references/multi-hop-strategy.md)
If not on latest patch → Guide user through patch upgrade first
Follow Pattern 1 Steps 4-6 for FIRST hop (5.2 → 6.0)
After first hop complete, repeat for next hops
IMPORTANT: After each hop, align load_defaults to the new version before starting the next hop
Pattern 3: Breaking Changes Analysis Only
User says: "What breaking changes affect my app for Rails 8.0?"
This pattern is analysis-only — it intentionally skips Step 2 (Dual-Boot setup) and Step 3 (Validate Upgrade Path) because the user is not yet committing to an upgrade.
Action - Step 0 (MANDATORY: Verify Latest Patch):
Check if on latest patch — warn if not, recommend patching first
Action - Step 1 (MANDATORY: Verify Tests Pass):
Run test suite first
If tests fail → Warn user and recommend fixing first
If tests pass → Proceed with analysis
Action - Step 4 (Run Detection):
Load: workflows/direct-detection-workflow.md
Run detection directly using tools
Present findings summary
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 CI Config Check (Step 6, before opening the PR):
Every CI file in the repo enumerated (GitHub Actions, CircleCI, Jenkins, GitLab, etc.)
Ruby version, Rails matrix, and service versions diffed against the upgraded Gemfile
CI sync report produced with per-file verdict
All DRIFT entries fixed; overall verdict is OK
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
ALWAYS Verify Latest Patch First (MANDATORY - ensure app is on latest patch of current series before any version hop)
ALWAYS Run Test Suite (MANDATORY - no exceptions, no upgrade work until tests pass)
Block on Failing Tests (if tests fail, STOP and help fix them before any upgrade work)
Set Up Dual-Boot Early (dual-boot is Step 2, right after tests pass - run both versions during the entire transition)
Run Detection Directly (use Grep/Glob/Read tools - no script generation needed)
Always Use Actual Findings (no generic examples in reports)
Always Flag Custom Code (with ⚠️ warnings based on detected issues)
Always Use Templates (for consistency)
Always Check Quality (before delivery)
Load Workflows as Needed (don't hold everything in memory)
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.)
Check CI Config Before Opening the PR (run workflows/ci-sync-workflow.md to make sure every CI file matches the upgraded Gemfile — stale CI is the most common cause of red builds on upgrade PRs)
Align load_defaults After the Version Bump (load_defaults update happens AFTER the Rails version upgrade is complete)
Mention, Don't Auto-Run, Cleanup (after the upgrade ships, mention the upgrade-cleanup plugin. Delegate to it only when the user explicitly asks: "finish the upgrade", "clean up dual-boot", "drop the NextRails branches". Cleanup removes NextRails.next? / NextRails.current? branches and retires dual-boot scaffolding. Deprecation triage stays with this skill for the next hop.)
Success Criteria
A successful upgrade assistance session:
✅ Verified latest patch version (Step 0 - MANDATORY)
✅ Upgraded to latest patch if needed (before any minor/major hop)
✅ Ran test suite (Step 1 - MANDATORY)
✅ Verified all tests pass (blocked if tests failed)
✅ Recorded baseline metrics (test count, coverage)
✅ Set up dual-boot (Step 2 - early, before upgrading)
✅ Validated upgrade path (Step 3 - single-hop vs multi-hop, hops planned)
✅ 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
✅ Implemented changes and upgraded Rails version
✅ Verified CI config matches the upgraded Gemfile (Ruby, Rails matrix, services — all mismatches fixed before opening the PR)
✅ Aligned load_defaults (after upgrade is complete)
✅ Mentioned cleanup after the upgrade shipped (pointed to the upgrade-cleanup plugin without auto-running it; delegated only when the user explicitly asked)
✅ Provided clear next steps
✅ Offered to help implement changes
See CHANGELOG.md for version history and current version.
