Analyze Rails apps and provide upgrade assessments
Use this skill when working with analyze rails apps and provide upgrade assessments.
Analyze the current Rails application and provide a comprehensive upgrade assessment with selective file merging.
Check that we're in a Rails application by looking for these files:
Gemfile (must exist and contain 'rails')config/application.rb (Rails application config)config/environment.rb (Rails environment)If any of these are missing or don't indicate a Rails app, stop and inform the user this doesn't appear to be a Rails application.
Extract the current Rails version from:
Gemfile.lock for the exact installed version (look for rails (x.y.z))GemfileReport the exact current version (e.g., 7.1.3).
Use the GitHub CLI to fetch the latest Rails release:
gh api repos/rails/rails/releases/latest --jq '.tag_name'
This returns the latest stable version tag (e.g., v8.0.1). Strip the 'v' prefix for comparison.
Also check recent tags to understand the release landscape:
gh api repos/rails/rails/tags --jq '.[0:10] | .[].name'
Compare current and latest versions to classify the upgrade:
Use WebFetch to get the official Rails upgrade guide:
URL: https://guides.rubyonrails.org/upgrading_ruby_on_rails.html
Look for sections relevant to the version jump. The guide is organized by target version with sections like:
Extract and summarize the relevant sections for the user's specific upgrade path.
Use WebFetch to get the diff between versions from railsdiff.org:
URL: https://railsdiff.org/{current_version}/{target_version}
For example: https://railsdiff.org/7.1.3/8.0.0
This shows:
Summarize the key file changes.
Rails applications often include JavaScript packages that should be updated alongside Rails. Check for and report on these dependencies.
Check which package manager the app uses:
# Check for package.json (npm/yarn)
ls package.json 2>/dev/null
# Check for importmap (Rails 7+)
ls config/importmap.rb 2>/dev/null
If package.json exists, check for these Rails-related packages:
# Extract current versions of Rails-related packages
cat package.json | grep -E '"@hotwired/|"@rails/|"stimulus"|"turbo-rails"' || echo "No Rails JS packages found"
Key packages to check:
| Package | Purpose | Version Alignment |
|---|---|---|
@hotwired/turbo-rails | Turbo Drive/Frames/Streams | Should match Rails version era |
@hotwired/stimulus | Stimulus JS framework | Generally stable across Rails versions |
@rails/actioncable | WebSocket support | Should match Rails version |
@rails/activestorage | Direct uploads | Should match Rails version |
@rails/actiontext | Rich text editing | Should match Rails version |
@rails/request.js | Rails UJS replacement | Should match Rails version era |
For npm/yarn projects, check for available updates:
# Using npm
npm outdated @hotwired/turbo-rails @hotwired/stimulus @rails/actioncable @rails/activestorage 2>/dev/null
# Or check latest versions directly
npm view @hotwired/turbo-rails version 2>/dev/null
npm view @rails/actioncable version 2>/dev/null
If the app uses importmap-rails, check config/importmap.rb for pinned versions:
cat config/importmap.rb | grep -E 'pin.*turbo|pin.*stimulus|pin.*@rails' || echo "No importmap pins found"
To update importmap pins:
bin/importmap pin @hotwired/turbo-rails
bin/importmap pin @hotwired/stimulus
Include in the upgrade summary:
### JavaScript Dependencies
**Package Manager**: [npm/yarn/importmap/none]
| Package | Current | Latest | Action |
|---------|---------|--------|--------|
| @hotwired/turbo-rails | 8.0.4 | 8.0.12 | Update recommended |
| @rails/actioncable | 7.1.0 | 8.0.0 | Update with Rails |
| ... | ... | ... | ... |
**Recommended JS Updates:**
- Run `npm update @hotwired/turbo-rails` (or yarn equivalent)
- Run `npm update @rails/actioncable @rails/activestorage` to match Rails version
Provide a comprehensive summary including all findings from Steps 1-7:
Rate the upgrade as Small, Medium, or Large based on:
| Factor | Small | Medium | Large |
|---|---|---|---|
| Version jump | Patch only | Minor version | Major version |
| Breaking changes | None | Few, well-documented | Many, significant |
| Config changes | Minimal | Moderate | Extensive |
| Deprecations | None active | Some to address | Many requiring refactoring |
| Dependencies | Compatible | Some updates needed | Major dependency updates |
List the most important changes the user needs to handle:
bundle update railsrails app:update directly - use the selective merge process belowAnalyze Rails apps and provide upgrade assessments
Use this skill when working with analyze rails apps and provide upgrade assessments.
rails app:update)IMPORTANT: Do NOT run rails app:update as it overwrites files without considering local customizations. Instead, follow this selective merge process:
Before any upgrade, identify files with local customizations:
# Check for uncommitted changes
git status
# List config files that differ from a fresh Rails app
# These are the files we need to be careful with
git diff HEAD --name-only -- config/ bin/ public/
Create a mental list of files in these categories:
Based on the railsdiff output from Step 6, categorize each changed file:
| Category | Action | Example |
|---|---|---|
| New files | Create directly | config/initializers/new_framework_defaults_X_Y.rb |
| Unchanged locally | Safe to overwrite | public/404.html (if not customized) |
| Customized locally | Manual merge needed | config/application.rb, bin/dev |
| Comment-only changes | Usually skip | Minor comment updates in config files |
Present the user with a clear upgrade plan:
## Upgrade Plan: Rails X.Y.Z → A.B.C
### New Files (will be created):
- config/initializers/new_framework_defaults_A_B.rb
- bin/ci (new CI script)
### Safe to Update (no local customizations):
- public/400.html
- public/404.html
- public/500.html
### Needs Manual Merge (local customizations detected):
- config/application.rb
└─ Local: i18n configuration
└─ Rails: [describe new Rails changes if any]
- config/environments/development.rb
└─ Local: letter_opener mailer config
└─ Rails: [describe new Rails changes]
- bin/dev
└─ Local: foreman + Procfile.dev setup
└─ Rails: changed to simple ruby script
### Skip (comment-only or irrelevant changes):
- config/puma.rb (only comment changes)
After user confirms the plan:
Create them directly using the content from railsdiff or by extracting from a fresh Rails app:
# Generate a temporary fresh Rails app to extract new files
cd /tmp && rails new rails_template --skip-git --skip-bundle
# Then copy needed files
Or use the Rails generator for specific files:
bin/rails app:update:configs # Only updates config files, still interactive
Overwrite these files as they have no local customizations.
For each file needing merge, show the user:
Example merge for config/application.rb:
# KEEP local customizations:
config.i18n.available_locales = [:de, :en]
config.i18n.default_locale = :de
config.i18n.fallbacks = [:en]
# ADD new Rails 8.1 settings if needed:
# (usually none required - new defaults come via new_framework_defaults file)
After file updates, run any new migrations:
bin/rails db:migrate
Check for new migrations that were added:
ls -la db/migrate/ | tail -10
After completing the merge:
Start the Rails server and check for errors:
bin/dev # or bin/rails server
Check the Rails console:
bin/rails console
Run the test suite:
bin/rails test
Review deprecation warnings in logs
After verifying the app works:
config/initializers/new_framework_defaults_X_Y.rbconfig/application.rb:
config.load_defaults X.Y # Update to new version
new_framework_defaults_X_Y.rb fileAnalyze Rails apps and provide upgrade assessments
Use this skill when working with analyze rails apps and provide upgrade assessments.
gh CLI is not authenticated, instruct the user to run gh auth logingit checkout to restore if needed
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.
Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.
CLI to manage emails via IMAP/SMTP. Use `himalaya` to list, read, write, reply, forward, search, and organize emails from the terminal. Supports multiple accounts and message composition with MML (MIME Meta Language).