sorbet-adoption

Sorbet Adoption

This is a playbook for bringing an untyped Ruby or Rails codebase to Sorbet # typed: strict through a series of reviewable PRs. It is distilled from a rollout that took a Rails app and its client gem from no annotations to about 300 strict files in 22 stacked PRs.

Load sorah-guides:sorbet before writing any annotation. That skill defines how types are written. This one decides order, scope and mechanics. For branch and stack mechanics use /gh-stack; for commits and PR bodies use /sorah-guides:commit and /sorah-guides:pull-request.

The rollout runs in this order:

1. Survey and decide
2. Infra PR
3. Prep PRs
4. Sigils PR
5. Slices, bottom-up
6. Integrate
7. Review
8. Keep current

Lessons that shaped this playbook

• typed: true is not the goal.
  • The first pass of the original rollout raised 17 slices to true and was green. Yet the code carried 6 method signatures across about 1750 methods, because true demands none and the exit condition was "bump and srb tc green".
  • Every slice had to be redone to strict, which surfaced over 3000 errors (about two thirds of them missing signatures).
  • Plan for strict from the start.
• Casts are debt.
  • The strict pass then left more than 250 #: as !nil casts, and a later pass replaced them with restructures, raising readers and Must.
  • Write nil and union handling the sorbet skill's way from the first commit.
• Shared shims belong in the infra PR. Slices that each added the same logger method or the same timestamp cast produced add/add conflicts and duplicated work. One shim at the bottom of the stack removed every copy.
• Cross-slice errors appear only after stacking. Slices typed in parallel are each green alone. Once chained, a single wrong return type in a low layer caused 87 errors above it. Budget an integration pass.
• Agent output needs a real review. Many agents writing casts in security-sensitive code surfaced real bugs: a positional initialize that silently received a Hash, and controllers reading current_user under a gate that a machine credential passes. They also produced workarounds that turned out to be unnecessary.