rails-upgrade-assistant skill

---
name: rails-upgrade-assistant
description: Analyzes Rails applications and generates comprehensive upgrade reports with breaking changes, deprecations, and step-by-step migration guides for Rails 7.0 through 8.1.1. Use when upgrading Rails applications, planning multi-hop upgrades, or querying version-specific changes.
---

# Rails Upgrade Assistant Skill v1.0

## How It Works

Three-step process:

1. **Detection Script** — Generate a bash script that scans the codebase for breaking changes with file:line references
2. **User Runs Script** — User executes it, gets `rails_{version}_upgrade_findings.txt`
3. **Reports** — Generate upgrade report and app:update preview based on actual findings (not hypothetical)

---

## Sequential Upgrade Strategy

### ⚠️ Version Skipping is NOT Allowed

Rails upgrades MUST follow this exact sequence:
```
7.0.x → 7.1.x → 7.2.x → 8.0.x → 8.1.x
```

**You CANNOT skip versions.** Examples:
- ❌ 7.0 → 7.2 (skips 7.1)
- ❌ 7.0 → 8.0 (skips 7.1 and 7.2)
- ✅ 7.0 → 7.1 (correct)
- ✅ 7.1 → 7.2 (correct)

If user requests a multi-hop upgrade (e.g., 7.0 → 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

---

## Available Resources

### Core Documentation
- `docs/README.md` - Human-readable overview
- `docs/QUICK-REFERENCE.md` - Command cheat sheet
- `docs/USAGE-GUIDE.md` - Comprehensive how-to

### Version-Specific Guides (Load as needed)
- `version-guides/upgrade-7.0-to-7.1.md` - Rails 7.0 → 7.1
- `version-guides/upgrade-7.1-to-7.2.md` - Rails 7.1 → 7.2
- `version-guides/upgrade-7.2-to-8.0.md` - Rails 7.2 → 8.0
- `version-guides/upgrade-8.0-to-8.1.md` - Rails 8.0 → 8.1

### Workflow Guides (Load when generating deliverables)
- `workflows/upgrade-report-workflow.md` - How to generate upgrade reports
- `workflows/detection-script-workflow.md` - How to generate detection scripts
- `workflows/app-update-preview-workflow.md` - How to generate app:update previews

### Examples (Load when user needs clarification)
- `examples/simple-upgrade.md` - Single-hop upgrade example
- `examples/multi-hop-upgrade.md` - Multi-hop upgrade example
- `examples/detection-script-only.md` - Detection script only request
- `examples/preview-only.md` - Preview only request

### Reference Materials
- `reference/breaking-changes-by-version.md` - Quick lookup
- `reference/multi-hop-strategy.md` - Multi-version planning
- `reference/deprecations-timeline.md` - Deprecation tracking
- `reference/testing-checklist.md` - Comprehensive testing
- `reference/pattern-file-guide.md` - How to use pattern files
- `reference/quality-checklist.md` - Pre-delivery verification
- `reference/troubleshooting.md` - Common issues and solutions

### Detection Script Resources
- `detection-scripts/patterns/rails-72-patterns.yml` - Rails 7.2 patterns
- `detection-scripts/patterns/rails-80-patterns.yml` - Rails 8.0 patterns
- `detection-scripts/patterns/rails-81-patterns.yml` - Rails 8.1 patterns
- `detection-scripts/templates/detection-script-template.sh` - Bash template

### Report Templates
- `templates/upgrade-report-template.md` - Main upgrade report structure
- `templates/app-update-preview-template.md` - Configuration preview

---

## Workflow

### Phase 1: Generate Detection Script

1. Detect current Rails version from `Gemfile.lock`
2. Read `detection-scripts/patterns/rails-{VERSION}-patterns.yml`
3. Read `detection-scripts/templates/detection-script-template.sh`
4. Read `workflows/detection-script-workflow.md`
5. Generate version-specific bash script and deliver to user

### Phase 2: User Runs Script

User runs the script, gets findings. Wait for them to share `rails_{version}_upgrade_findings.txt`.

### Phase 3: Generate Reports

1. Parse findings.txt — extract breaking changes and affected files
2. Read `version-guides/upgrade-{FROM}-to-{TO}.md`
3. Read `workflows/upgrade-report-workflow.md` and `workflows/app-update-preview-workflow.md`
4. Generate **Comprehensive Upgrade Report** with real code from the user's project
5. Generate **app:update Preview** with actual config file diffs

---

## Quality

Before delivering any output, verify against `reference/quality-checklist.md`. Key rules:
- Replace all {PLACEHOLDERS} with actual values
- Use ACTUAL findings from the script, not generic examples
- Include real file:line references and real code from the user's project
- Flag custom code with warnings

---

## Bundled Resources

Load these as needed — don't read everything upfront:

| Directory | When to load |
|-----------|-------------|
| `workflows/` | Before generating detection scripts or reports |
| `version-guides/` | When you need version-specific breaking changes |
| `templates/` | When generating report output |
| `detection-scripts/patterns/` | When building the detection script |
| `examples/` | When user needs clarification on the process |
| `reference/` | For quality checks, troubleshooting, pattern file format |