Analyze Rails Apps and Generate Upgrade Roadmaps

This workflow assesses a Rails application's upgrade path and prepares a selective file merge. It starts by confirming the project has a Rails Gemfile, config/application.rb, and config/environment.rb. Resolve the current version from Gemfile.lock where possible; a Gemfile constraint alone is not necessarily the exact installed version. Compare that version with a verified target release and classify the change as patch, minor, or major.

The assessment consults official upgrade guidance, release notes, and Railsdiff for the relevant version jump. It identifies breaking changes, deprecations, migrations, default configuration changes, new files, initializers, dependencies, and bin scripts. JavaScript dependencies also need review, including Turbo, Stimulus, Action Cable, Active Storage, Action Text, and request.js where present. Check the actual package manager or importmap setup rather than assuming every Rails application uses the same frontend arrangement.

Use it to estimate upgrade complexity and produce an actionable plan for a real Rails application. Small, Medium, and Large assessments consider version distance, breaking changes, configuration work, deprecations, and dependency compatibility. A release lookup example is:

gh api repos/rails/rails/releases/latest --jq '.tag_name'

This is a lookup to perform when assessing the application, not a fixed claim that an example version is current. If exact Railsdiff versions are unavailable, any fallback comparison is approximate and must not be mistaken for the exact target's generated files.

Assessment is read-only by default. Dependency updates, generated files, migrations, and application startup require implementation scope. Do not run rails app:update blindly or overwrite defaults merely because they are generated. Existing local behavior must be inspected and preserved; uncommitted differences alone do not reveal every customization in tracked files.

Inputs include the application, exact current and target versions, lockfiles, current configuration, relevant release guidance, and the authorized environment. Compare tracked files with a clean application generated using the exact current Rails version and options before declaring them uncustomized. Classify changes as new files, verified unchanged defaults, customized files needing manual merge, or irrelevant and comment-only differences.

The output is an upgrade summary and file-by-file plan explaining what will be created, updated, merged, or skipped. For manual merges, show the local content, new defaults, and suggested combination. Preserve custom settings while adding necessary framework behavior and removing deprecated configuration. Generate reference files in a fresh unique temporary directory after inspecting generator side effects.

Implementation verification includes relevant tests, startup, console checks, and deprecation review. Confirm the database and environment before migrations, use a disposable development database where appropriate, and keep tested restoration separate from Git recovery. Enable new framework defaults individually with checks before updating load_defaults and removing the transition initializer. Stop if a proposed overwrite would lose local customizations; a source-control rollback cannot undo database or remote side effects.