Skip to content

ombulabs/claude-code_rails-upgrade-skill / rails-upgrade

rails-upgrade

Verified

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, querying version-specific changes, or answering what stands between the app and the next Rails version. Based on FastRuby.io methodology and "The Complete Guide to Upgrade Rails" ebook.

FileKindSize
SKILL.mdskill md11.0 KB
detection-scripts/gem_limits.rbscript6.0 KB
detection-scripts/hop.rbscript2.2 KB
detection-scripts/patterns/rails-40-patterns.expectations.ymlconfig43.8 KB
detection-scripts/patterns/rails-40-patterns.ymlconfig96.5 KB
detection-scripts/patterns/rails-41-patterns.expectations.ymlconfig25.6 KB
detection-scripts/patterns/rails-41-patterns.ymlconfig59.8 KB
detection-scripts/patterns/rails-42-patterns.expectations.ymlconfig27.5 KB
detection-scripts/patterns/rails-42-patterns.ymlconfig48.7 KB
detection-scripts/patterns/rails-50-patterns.expectations.ymlconfig1.9 KB
detection-scripts/patterns/rails-50-patterns.ymlconfig8.1 KB
detection-scripts/patterns/rails-51-patterns.expectations.ymlconfig4.2 KB
detection-scripts/patterns/rails-51-patterns.ymlconfig15.0 KB
detection-scripts/patterns/rails-52-patterns.expectations.ymlconfig5.0 KB
detection-scripts/patterns/rails-52-patterns.ymlconfig14.7 KB
detection-scripts/patterns/rails-60-patterns.expectations.ymlconfig1007 B
detection-scripts/patterns/rails-60-patterns.ymlconfig14.2 KB
detection-scripts/patterns/rails-70-patterns.expectations.ymlconfig4.0 KB
detection-scripts/patterns/rails-70-patterns.ymlconfig11.2 KB
detection-scripts/patterns/rails-71-patterns.expectations.ymlconfig3.1 KB
detection-scripts/patterns/rails-71-patterns.ymlconfig9.5 KB
detection-scripts/patterns/rails-72-patterns.expectations.ymlconfig1.2 KB
detection-scripts/patterns/rails-72-patterns.ymlconfig6.1 KB
detection-scripts/patterns/rails-80-patterns.expectations.ymlconfig6.6 KB
detection-scripts/patterns/rails-80-patterns.ymlconfig21.2 KB
detection-scripts/patterns/rails-81-patterns.expectations.ymlconfig4.3 KB
detection-scripts/patterns/rails-81-patterns.ymlconfig13.2 KB
detection-scripts/scan_patterns.rbscript42.8 KB
examples/multi-hop-upgrade.mdmarkdown18.9 KB
examples/simple-upgrade.mdmarkdown4.0 KB
references/breaking-changes-by-version-reference.mdmarkdown3.9 KB
references/deprecation-warnings-reference.mdmarkdown10.7 KB
references/gem-compatibility-reference.mdmarkdown8.2 KB
references/js-compressor-sprockets-mismatch-reference.mdmarkdown4.7 KB
references/multi-hop-strategy-reference.mdmarkdown8.8 KB
references/next-hop-readiness-reference.mdmarkdown2.1 KB
references/no-test-suite-smoke-reference.mdmarkdown4.7 KB
references/request-patterns-reference.mdmarkdown3.7 KB
references/sequential-strategy-reference.mdmarkdown2.1 KB
references/staying-current-reference.mdmarkdown7.8 KB
references/testing-checklist-reference.mdmarkdown6.3 KB
templates/app-update-preview-template.mdmarkdown4.3 KB
templates/upgrade-report-template.mdmarkdown10.2 KB
version-guides/upgrade-3.2-to-4.0.mdmarkdown68.0 KB
version-guides/upgrade-4.0-to-4.1.mdmarkdown66.7 KB
version-guides/upgrade-4.1-to-4.2.mdmarkdown60.7 KB
version-guides/upgrade-4.2-to-5.0.mdmarkdown9.7 KB
version-guides/upgrade-5.0-to-5.1.mdmarkdown19.1 KB
version-guides/upgrade-5.1-to-5.2.mdmarkdown17.7 KB
version-guides/upgrade-5.2-to-6.0.mdmarkdown6.4 KB
version-guides/upgrade-6.0-to-6.1.mdmarkdown6.8 KB
version-guides/upgrade-6.1-to-7.0.mdmarkdown14.7 KB
version-guides/upgrade-7.0-to-7.1.mdmarkdown13.2 KB
version-guides/upgrade-7.1-to-7.2.mdmarkdown11.2 KB
version-guides/upgrade-7.2-to-8.0.mdmarkdown23.1 KB
version-guides/upgrade-8.0-to-8.1.mdmarkdown14.0 KB
workflows/00-verify-latest-patch-workflow.mdmarkdown1.7 KB
workflows/01-run-test-suite-workflow.mdmarkdown12.7 KB
workflows/02-resolve-deprecation-warnings-workflow.mdmarkdown6.3 KB
workflows/03-validate-upgrade-path-workflow.mdmarkdown1.8 KB
workflows/04-setup-next-rails-workflow.mdmarkdown1.5 KB
workflows/05-detect-breaking-changes-workflow.mdmarkdown20.0 KB
workflows/06-check-gem-compatibility-workflow.mdmarkdown11.1 KB
workflows/07-boot-smoke-test-workflow.mdmarkdown7.3 KB
workflows/08-generate-upgrade-report-workflow.mdmarkdown12.7 KB
workflows/09-generate-app-update-preview-workflow.mdmarkdown7.3 KB
workflows/10-implement-and-upgrade-workflow.mdmarkdown2.5 KB
workflows/11-sync-ci-workflow.mdmarkdown8.6 KB
workflows/12-align-load-defaults-workflow.mdmarkdown952 B
workflows/13-mention-cleanup-workflow.mdmarkdown1.3 KB

workflows/06-check-gem-compatibility-workflow.md

View on GitHub
# Workflow 06: Check Gem Compatibility

**Purpose:** Determines which gems must be bumped before the Rails version change can resolve. Produce a per-lockfile gem compatibility report against the target Rails version. Output is three buckets (`required bumps`, `blockers`, `already compatible`) that feed the upgrade report's gem-update section.

**When to use:** Workflow 06 of the `SKILL.md` index, after breaking-change detection and before report generation. The report's `bundle update` plan depends on this output.

## Inputs

- `Gemfile.lock`
- `next_rails` installed in the project (not needed for the first pass)
- Target Rails version

## Outputs

- Three buckets — required bumps, blockers, already compatible — passed into Workflow 08's report so the gem-update section reflects real per-lockfile data

## Gates (must be true before the next workflow that runs)

- If any blockers exist, `references/gem-compatibility-reference.md` loaded for the fork/replace/vendor playbook and the gem update order. Skip otherwise.

## Pre-upgrade checklist (FastRuby.io best practices, recommended before starting any upgrade)

**Dependency Audit**
- [ ] Run `bundle outdated`
- [ ] Check gem compatibility with target Rails version
- [ ] Identify gems that need upgrading first

---

## First pass: declared limits in the lockfile

Run `ruby <skill>/detection-scripts/gem_limits.rb --target <target>`. It reads only the lockfile (no network, no next_rails) and lists the locked gems whose gemspec excludes the target. Each one lands in required bumps or blockers; the check below says which, and the version to bump to.

---

## Two checks, one orchestrator

The orchestrator picks **one primary** and only escalates to secondary when needed. Don't run both by default.

| Check | Source | Strengths | Weaknesses |
|---|---|---|---|
| **Primary**: `bundle_report compatibility` | `next_rails` (local CLI) | Synchronous, pre-bucketed output, gives upgrade target version per gem, no third-party uptime concern | Reads gemspec metadata only — can miss transitive resolution conflicts |
| **Secondary**: railsbump.org API | `https://api.railsbump.org` | Tests actual lockfile resolution graph against a real Rails release | Async (30-600s polling), depends on third-party uptime, occasional `unknown` results |

Reach for the secondary only when:

1. `bundle_report` cannot run (next_rails not installed; `bundle exec` fails in the env).
2. `bundle_report` reports a gem under "no new compatible versions" and the user wants a second opinion before forking/replacing it.
3. The user explicitly asks for cross-validation.
4. There is reason to suspect a transitive resolution conflict.

---

## Primary: `bundle_report compatibility`

```bash
bundle exec bundle_report compatibility --rails-version=<target>
```

Requires `next_rails` installed in the project (the dual-boot skill installs it in Workflow 04) and network access (Bundler fetches gem metadata).

### Output shape

`bundle_report` prints three sections. Output is stable; parse with regex.

```
=> incompatible with rails X (with new versions that are compatible):
these gems will need to be upgraded before upgrading to rails X.

paper_trail 2.7.2 - upgrade to 7.1.3
simple_form 2.1.3 - upgrade to 3.2.0
...

=> incompatible with rails X (with no new compatible versions):
these gems will need to be removed or replaced before upgrading to rails X.

rails3_acts_as_paranoid 0.1.1 (loaded from git) - new version, 0.2.5, is not compatible with rails X

=> incompatible with rails X (with no new versions):
these gems will need to be upgraded by us or removed before upgrading to rails X.

strong_parameters 0.2.3 - new version not found
turbo-sprockets-rails3 0.3.14 - new version not found
```

### Bucket mapping

| `bundle_report` section | Bucket | Plan |
| --- | --- | --- |
| "with new versions that are compatible" | required bumps | `bundle update <gem> --conservative` to the listed target version |
| "with no new compatible versions" | blockers | Replace gem, fork the in-flight PR, or drop the dependency |
| "with no new versions" | blockers | Vendor / fork / replace — gem is abandoned or pre-extraction |
| (gem not listed in any section) | already compatible | Note the locked version; no action |

If the command produces no output at all, or if the output contains no `=> incompatible with rails X` headers despite an exit code of 0, treat it as `bundle_report` failing or producing an unparseable result — escalate to the secondary check rather than assuming "all gems compatible." A future `next_rails` release that reformats the output would otherwise silently produce empty buckets.

---

## Secondary: railsbump API

Use only when the orchestrator triggered the secondary path (see "Two checks, one orchestrator" above).

### POST `/lockfiles`

```bash
curl -sS -X POST https://api.railsbump.org/lockfiles \
  -H 'Content-Type: application/json' \
  --data-binary "$(jq -Rs '{lockfile: {content: .}}' < Gemfile.lock)"
```

The lockfile content must be JSON-escaped — the `jq -Rs` filter does that. Mirrors `bin/api_check_lockfile` in the railsbump repo.

**202 Accepted** response shape:

```json
{
  "slug": "abc123",
  "status": "pending",
  "status_url": "https://api.railsbump.org/lockfiles/abc123",
  "retry_after_seconds": 45,
  "message": "Compatibility check is running. ..."
}
```

`Location` and `Retry-After` headers are also set. Capture `slug`, `status_url`, `retry_after_seconds`.

**422 Unprocessable Content** response: `{"errors": [...]}`. Typical causes: `content` blank, malformed Gemfile.lock that the server can't parse, no Rails entry. Surface the messages verbatim and stop — do not retry.

### GET `/lockfiles/:slug`

```bash
curl -sS https://api.railsbump.org/lockfiles/<slug> | jq .
```

**200 OK** response shape:

```json
{
  "slug": "abc123",
  "status": "complete",
  "lockfile_checks": [
    {
      "target_rails_version": "7.2.0",
      "ruby_version": "3.3.0",
      "bundler_version": "2.5.6",
      "rubygems_version": "3.5.6",
      "status": "complete",
      "gem_checks": [
        {
          "name": "devise",
          "locked_version": "4.8.1",
          "status": "complete",
          "result": "incompatible",
          "earliest_compatible_version": "4.9.4",
          "error_message": null
        }
      ]
    }
  ]
}
```

Top-level `status`: `pending` | `complete` | `failed`. Per-`gem_check` `result`: typically `compatible` | `incompatible` | `unknown`. Treat any unrecognized value as `unknown` and surface it.

**404** `{"errors": ["Lockfile not found"]}`: slug expired or never existed.

### Polling

Wait `retry_after_seconds` (clamped 30-600 by the server). Then GET `status_url`. Loop until top-level `status` is `complete` or `failed`.

**Cap: 10 polls OR 30 minutes total elapsed, whichever comes first.** Track elapsed time across the polls so the 30-minute ceiling kicks in regardless of the per-poll wait. (The server returns a `retry_after_seconds` derived from gem count and worker concurrency — both fixed for a given lockfile — so the value is constant across polls, not growing. The 30-minute cap bounds the *total* check; the 10-poll cap protects against a stuck pending state.) At the cap, give up — report the slug to the user, note that the secondary check stalled, and proceed with whatever the primary produced.

Do not poll faster than the server's `retry_after_seconds`. The check is per-gem CPU work; hammering the endpoint will not return results sooner.

### Bucket mapping

The API may return multiple `lockfile_checks` (one per Rails release it tested against). Pick the one whose `target_rails_version` matches the upgrade hop's target.

| `gem_check` shape | Bucket | Plan |
| --- | --- | --- |
| `result: "incompatible"`, `earliest_compatible_version` set | required bumps | Bump to at least `earliest_compatible_version` |
| `result: "incompatible"`, `earliest_compatible_version` null | blockers | No compatible version exists — fork / vendor / replace |
| `result: "compatible"` | already compatible | Note the locked version |
| `result: "unknown"` or non-empty `error_message` | blockers (pending information) | Surface the error to the user. If `bundle_report` was also run and answered this gem, prefer its verdict (see Reconciliation). If railsbump is the only signal, treat as a blocker until the user can verify manually — do not silently assume compatible. |

---

## Reconciliation (when both checks ran)

When the orchestrator triggered the secondary because of an ambiguous primary result, both signals exist. Reconcile per gem:

- **Both agree the gem is compatible** → no action.
- **Both agree the gem needs a bump** → use the higher of the two target versions as the minimum bump.
- **`bundle_report` says "no new compatible versions" but railsbump returns `earliest_compatible_version`** → trust railsbump (it sees the actual resolution graph). Bump to that version and run tests.
- **Railsbump returns `unknown` / errored on a gem `bundle_report` already answered** → trust `bundle_report`.
- **They disagree on whether a gem is compatible at all** → run the user's test suite on the higher-version side. Tests are ground truth.

---

## Hand-off to the upgrade plan

Whichever check ran, the output handed to Workflow 08 is the same three buckets:

1. **Blockers** — incompatible gems with no compatible version, plus any gems where railsbump returned `unknown`/errored and `bundle_report` did not give a clean answer. The hop cannot complete until each one is resolved (see `references/gem-compatibility-reference.md` for the playbook). Mark "pending information" blockers separately so the user knows they may turn into "compatible" or "required bumps" once the missing data lands.
2. **Required bumps** — incompatible gems with a target version. Order top-level gems before their internal dependencies, so bundler can resolve the graph from the root. Example: bump `rspec-rails` before `rspec-mocks` — `rspec-rails` is the gem your Gemfile names directly, and it pulls `rspec-mocks` (and the rest of the rspec-* family) transitively.
3. **Already compatible** — no action needed, but note the locked version so the user can see headroom.

When the agent later runs the actual `bundle update`, prefer one gem at a time (`bundle update <gem> --conservative`) so a single bad resolution does not poison the whole graph.

---

## Caveats

- **Both checks need network.** `bundle_report` fetches gem metadata via Bundler; railsbump is a hosted service. Tell the user when either was skipped due to network failure — do not silently degrade.
- **Slugs expire.** Don't store railsbump slugs across sessions. Re-POST the lockfile if the user comes back later.
- **Compatibility ≠ green tests.** A `compatible` result means "the gem's gemspec accepts the target Rails" (and for railsbump, "the lockfile resolves"). Tests are still the ground truth.
- **Submit each lockfile once per session.** Cache the slug in conversation context.
- **Re-POST when the lockfile changes.** Any time the agent runs `bundle install`, `bundle update`, or otherwise modifies `Gemfile.lock` mid-session, discard the cached slug and POST again. The prior result was for a different lockfile and will mislead the gem-update plan.
planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall