rails-upgrade

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

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:

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:

• 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)
• NextRails.next? code patterns and examples
• CI configuration for dual-boot testing
• Post-upgrade cleanup (removing dual-boot branches)

DEPENDENCY: Requires the dual-boot skill

---

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

Upgrade Cleanup Requests (delegate to the upgrade-cleanup plugin):

• "Finish the upgrade"
• "Clean up after my Rails upgrade"
• "Remove the dual-boot setup"
• "Drop the NextRails branches"
• "We're done upgrading to Rails [version]"

---

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.0-to-4.1.md - Rails 4.0 → 4.1 (Spring, secrets.yml, enums)
• version-guides/upgrade-4.1-to-4.2.md - Rails 4.1 → 4.2 (ActiveJob, Web Console)
• 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/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_rails bundle_report compatibility) and the secondary (railsbump.org API) and the rules for when to escalate.
• workflows/boot-smoke-test-workflow.md - Load in Step 4.6 - Run a Rails-loading command against Gemfile.next to catch gem-level runtime incompat that the resolver can't see (gems calling removed Rails internals or require-ing removed files).
• 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

External Dependencies

• dual-boot skill - Dual-boot setup and management with next_rails (Step 2) (https://github.com/ombulabs/claude-code_dual-boot-skill)
• rails-load-defaults skill - Incremental load_defaults alignment (Step 7, final step) (https://github.com/ombulabs/claude-code_rails-load-defaults-skill)

Reference Materials

• references/deprecation-warnings.md - Finding and fixing deprecations
• references/staying-current.md - Keeping up with Rails releases
• references/breaking-changes-by-version.md - Quick lookup
• references/multi-hop-strategy.md - Multi-version planning
• references/testing-checklist.md - Comprehensive testing
• 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
• templates/app-update-preview-template.md - Configuration preview

---

High-Level Workflow

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.

Step 4.6: Boot Smoke Test on Gemfile.next

Catches the gem-internal incompatibilities that Step 4 (codebase grep) and
Step 4.5 (resolver-level compat check) cannot see.

A gem can declare loose Rails constraints — no upper bound on activerecord /
activesupport — and `bundle_report compatibility` plus `bundle install` will
both call it "compatible." But at runtime, the gem may:

  - call a Rails internal that was removed at the target version
    (e.g. database_cleaner-active_record 2.1.x calling
    AR::ConnectionAdapters#schema_migration, removed in Rails 7.2)
  - require a file that was removed at the target version
    (e.g. jbuilder 2.11.x doing `require "active_support/proxy_object"`,
    removed in Rails 8.0)

These surface only when something boots Rails. Catching them here, before
the report is written, lets them land in fix-before-bump where they belong
instead of mid-implementation.

1. Read: workflows/boot-smoke-test-workflow.md
2. Run a Rails-loading command against Gemfile.next:
     BUNDLE_GEMFILE=Gemfile.next bundle exec rspec --dry-run
   (or `bin/rails runner "puts Rails.version"`, or `bundle exec rspec` if
   the suite is fast enough — anything that triggers
   `Bundler.require(*Rails.groups)` and the framework boot.)
3. If boot fails, capture the LoadError / NoMethodError trace, identify
   the offending gem (grep the bundle paths for the missing constant or
   file), check rubygems for a newer version with target-Rails compat,
   and add the bump to the fix-before-bump bucket for Step 5.
4. Re-run the boot smoke test until it succeeds. Then proceed to Step 5.

Step 5: 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: A report covering findings grouped into the two buckets defined in workflows/direct-detection-workflow.md — fix-before-bump (kind: breaking and kind: deprecation) and fix-when-ready (kind: migration and kind: optional) — 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. Apply fix-before-bump changes (`kind: breaking` and `kind: deprecation`). Most fixes are direct rewrites — the new API typically works on both sides of the dual-boot pair (e.g., `update_attributes` → `update`). Use `NextRails.next?` only when the fix requires target-version-only APIs that don't exist in the current Rails
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 load_defaults-triggered runtime deprecation warnings about future Rails versions during this hop. This caveat covers post-bump runtime warnings emitted by Rails X+1 about behavior scheduled to change in X+2 — typically surfaced once load_defaults X.Y flips on in Step 7. Those belong to the next upgrade cycle and are addressed before the next version bump.

This is not a contradiction of fix-before-bump. The kind: deprecation patterns from Step 4's detection are warnings emitted by the current Rails version about APIs that go away at the target version — they stay in fix-before-bump and should be addressed in this hop.

Triaging tomorrow's deprecation warnings 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):

1. Read Gemfile.lock for exact Rails version
2. Compare against latest patch for that series (see references/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

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 (Set Up Dual-Boot):

1. DELEGATE to the dual-boot skill for setup
2. Set up next_rails, Gemfile.next, and dual-boot CI

Action - Step 3 (Validate Upgrade Path):

1. Validate upgrade path (single-hop vs multi-hop)

Action - Step 4 (Run Detection Directly):

1. Load: workflows/direct-detection-workflow.md
2. Load: detection-scripts/patterns/rails-{VERSION}-patterns.yml
3. Use Grep/Glob/Read tools to search for each pattern
4. Collect findings with file:line references

Action - Step 4.5 (Check Gem Compatibility):

1. Load: workflows/gem-compatibility-workflow.md and follow it
2. Run primary check (bundle_report compatibility); escalate to railsbump only when the workflow's conditions trigger
3. Pass the resulting buckets (required bumps, blockers, already compatible) into Step 5's report
4. If blockers exist, load references/gem-compatibility.md for the fork/replace/vendor playbook

Action - Step 5 (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

Action - Step 6 (Implement & Upgrade):

1. Apply fix-before-bump changes (kind: breaking and kind: deprecation). Most fixes are direct rewrites — the new API typically works on both sides of the dual-boot pair (e.g., update_attributes → update). Use NextRails.next? only when the fix requires target-version-only APIs that don't exist in the current Rails
2. Update Gemfile to target Rails version
3. Run tests against both versions
4. Check CI config matches the upgraded Gemfile (workflows/ci-sync-workflow.md) — fix any mismatches before declaring Step 6 complete
5. Deploy and verify

Action - Step 7 (Align load_defaults - FINAL):

1. DELEGATE to the rails-load-defaults skill
2. Walk through each config incrementally after the upgrade is complete

Pattern 2: Multi-Hop Request

User says: "Help me upgrade from Rails 5.2 to 8.1"

Action - Step 0 (MANDATORY: Verify Latest Patch):

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

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 (Set Up Dual-Boot):

1. DELEGATE to the dual-boot skill for setup (if not already set up)
2. Dual-boot stays active throughout the multi-hop process

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: references/multi-hop-strategy.md
4. Follow Pattern 1 Steps 4-6 for FIRST hop (5.2 → 6.0)
5. After first hop complete, repeat for next hops
6. 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):

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

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 4 (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)
• Findings grouped into the two buckets — fix-before-bump (kind: breaking and kind: deprecation) and fix-when-ready (kind: migration and kind: optional) — with 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

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. Set Up Dual-Boot Early (dual-boot is Step 2, right after tests pass - run both versions during the entire transition)
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 (patch check → tests → dual-boot → validate path → detection → reports → implement → load_defaults)
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. DELEGATE to the dual-boot skill for patterns and setup.)
14. 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)
15. Align load_defaults After the Version Bump (load_defaults update happens AFTER the Rails version upgrade is complete)
16. 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.