generating-sorbet

name	generating-sorbet
description	Generates or updates Sorbet type signatures in separate .rbi files. Triggers when creating, updating, or maintaining type signatures for Ruby source files. Use for rbi/**/*.rbi shim files without editing source.

Defaults (ruby-rails plugin)

• Toolchain: mise — use mise exec -- when the project uses mise
• Ruby: 4.0.0+ unless the project pins otherwise
• Commands: Prefer mise exec -- bundle exec over bare bundle exec when Gemfile is present
• Pairing: Use generating-rbs-inline vs generating-rbs (and Sorbet inline vs RBI) based on project convention — never mix systems in one file

Sorbet RBI Generation Skill

Generate or update Sorbet type signatures in separate .rbi files. Supports both full generation from scratch and partial updates for individual changed files. RBI files are used when you cannot or should not modify the original Ruby source - such as for gems, generated code, or legacy codebases.

Instructions

When generating Sorbet RBI signatures, always follow these steps.

Copy this checklist and track your progress:

Sorbet RBI Generation Progress:
- [ ] Step 1: Analyze the Ruby source
- [ ] Step 2: Generate RBI files
- [ ] Step 3: Eliminate `T.untyped` in signatures
- [ ] Step 4: Review and refine signatures
- [ ] Step 5: Validate signatures with Sorbet

Rules

• You MUST NOT run Ruby code of the project.
• You MUST NOT use T.untyped. Infer the proper type instead.
• You MUST NOT use T.unsafe - it bypasses type checking entirely.
• You MUST NOT use T.cast - it forces types without verification.
• You MUST ask the user to provide more details if something is not clear.
• You MUST prepend any command with bundle exec if the project has Gemfile.
• You MUST use sig { } block syntax for method signatures.
• You MUST add extend T::Sig to classes/modules before using sig.
• You MUST NOT add method bodies in RBI files - only signatures and empty method definitions.
• You MUST place RBI files in ./rbi directory.
• You MUST use the tracking file when processing multiple files to ensure no files are missed.

Multi-File Processing

When processing multiple Ruby files, create a tracking file to ensure all files are covered:

1. Create tracking file .sorbet-rbi-generation-todo.tmp:

   [ ] app/models/user.rb
   [ ] app/models/post.rb
   [ ] app/services/auth_service.rb

1. Process files one by one:

   • Take the next pending [ ] entry
   • Complete all steps (1-5) for that file
   • Mark as processed [x]
   • Save the tracking file
   • Continue to next pending entry

2. Cleanup: Remove the tracking file after all files are processed:

   rm .sorbet-rbi-generation-todo.tmp
   

If interrupted, the tracking file allows resuming from where you left off.

1. Analyze the Ruby Source

Always perform this step.

Read and understand the Ruby source file:

• Identify all classes, modules, methods, constants and instance variables.
• Note inheritance, module inclusion and definitions based on metaprogramming.
• Note visibility modifiers - public, private, protected.
• Note type parameters for generic classes.

2. Generate RBI Files

Always perform this step.

1. Determine the correct RBI directory:

   Place RBI files in ./rbi directory. Sorbet reads all .rbi files from this location.

   RBI files are needed to describe code Sorbet cannot understand statically:

   • Gem definitions
   • Methods created with define_method or method_missing
   • Constants from const_get/const_set
   • Dynamic ancestors added via extend
   • DSL-generated methods (Rails, ActiveRecord, etc.)

2. Create the RBI file with typed sigil:

   # typed: strict
   

3. Add extend T::Sig to each class/module:

   class MyClass
     extend T::Sig
   end
   

4. Add method stubs with signatures (no method bodies):

Example - Ruby Source:

class User
  attr_reader :name, :age

  def initialize(name, age)
    @name = name
    @age = age
  end

  def greet(greeting)
    "#{greeting}, #{@name}!"
  end
end

Example - RBI File (rbi/user.rbi):

# typed: strict

class User
  extend T::Sig

  sig { returns(String) }
  attr_reader :name

  sig { returns(Integer) }
  attr_reader :age

  sig { params(name: String, age: Integer).void }
  def initialize(name, age); end

  sig { params(greeting: String).returns(String) }
  def greet(greeting); end
end

• RBI files mirror structure but contain only signatures and empty method stubs
• See syntax.md for the full Sorbet RBI syntax guide

3. Eliminate T.untyped in Signatures

Always perform this step.

• Review all signatures and replace T.untyped with proper types.
• Use code context, method calls, and tests to infer types.
• Use T.untyped only as a last resort when type cannot be determined.

4. Review and Refine Signatures

Always perform this step.

• Verify signatures are correct, coherent, and complete.
• Remove unnecessary T.untyped types.
• Ensure all methods and attributes have signatures.
• Verify class hierarchy and module inclusions match the source.
• Fix any errors and repeat until signatures are correct.

5. Validate Signatures with Sorbet

Always perform this step.

Run Sorbet type checker to validate signatures:

srb tc

Or with bundle:

bundle exec srb tc

This checks:

• Signature syntax correctness
• Type consistency
• Method parameter/return type matching
• Class/module structure matching source

Fix any errors reported and repeat until validation passes.

References

• syntax.md - Sorbet RBI syntax guide
• references/ - Real-world RBI examples from stripe-ruby
• Sorbet RBI documentation - Official RBI docs