Context Compilation with cclsp + Sorbet

This skill provides patterns for LSP-powered context extraction and type-safe code generation using cclsp MCP tools, Solargraph, and Sorbet.

1. Tool Stack Overview

1.1 cclsp MCP Bridge

The cclsp MCP server provides Claude Code access to Language Server Protocol functionality:

Tool Purpose Use Case

mcp__cclsp__find_definition

Find symbol definitions Locate where methods/classes are defined

mcp__cclsp__find_references

Find all references Discover symbol usage patterns

mcp__cclsp__get_diagnostics

Get errors/warnings Validate code before execution

mcp__cclsp__rename_symbol

Rename symbols Safe refactoring

mcp__cclsp__rename_symbol_strict

Rename at position Precise symbol renaming

mcp__cclsp__restart_server

Restart LSP Recover from errors

1.2 Solargraph (Ruby LSP)

Solargraph provides Ruby-specific language intelligence:

• Method completion: Know what methods exist on objects

• Go to definition: Jump to class/method definitions

• Hover documentation: Inline YARD documentation

• Diagnostics: Syntax errors, undefined methods

• Workspace symbols: Search all symbols in project

Configuration (.solargraph.yml ):

include:

• "**/*.rb" exclude:
• spec/**/*
• test/**/*
• vendor/**/* reporters:
• rubocop
• require_not_found plugins: [] require_paths: [] domains: [] max_files: 5000

1.3 Sorbet (Type Checker)

Sorbet provides static type checking for Ruby:

• Static analysis: Catch type errors at compile time

• Runtime checking: Verify types during execution

• Gradual typing: Adopt incrementally with # typed: sigils

• IDE integration: LSP support via Sorbet Language Server

Type Sigils:

typed: ignore # Skip this file

typed: false # Only syntax errors

typed: true # Check types

typed: strict # Require signatures

typed: strong # No T.untyped

Common Commands:

Type check entire project

bundle exec srb tc

Type check specific file

bundle exec srb tc app/models/user.rb

Initialize Sorbet

bundle exec srb init

Generate RBI files

bundle exec tapioca init bundle exec tapioca dsl bundle exec tapioca gems

1.4 Supporting Tools

Tool Purpose Integration

parser gem AST analysis Deep code structure analysis

ripper Built-in Ruby parser Fallback parsing, always available

YARD Documentation Solargraph uses YARD for docs

Tapioca RBI generation Generate type signatures for gems

2. cclsp Tool Reference

2.1 find_definition

Find where a symbol is defined:

Usage Pattern

mcp__cclsp__find_definition( file_path: "app/services/payment_service.rb", symbol_name: "PaymentGateway", symbol_kind: "class" # optional: class, method, module )

Returns

{ "definitions": [ { "file": "app/gateways/payment_gateway.rb", "line": 5, "column": 1, "symbol": "PaymentGateway" } ] }

Common symbol_kind values:

• class

• Class definitions

• module

• Module definitions

• method

• Instance methods

• function

• Module/class methods

• variable

• Local/instance variables

• constant

• Constants

2.2 find_references

Find all usages of a symbol:

Usage Pattern

mcp__cclsp__find_references( file_path: "app/models/user.rb", symbol_name: "authenticate", include_declaration: true )

Returns

{ "references": [ { "file": "app/models/user.rb", "line": 45, "column": 3, "context": "def authenticate(password)" }, { "file": "app/controllers/sessions_controller.rb", "line": 12, "column": 8, "context": "if user.authenticate(params[:password])" } ] }

2.3 get_diagnostics

Get errors and warnings for a file:

Usage Pattern

mcp__cclsp__get_diagnostics( file_path: "app/services/order_service.rb" )

Returns

{ "diagnostics": [ { "severity": 1, # 1=Error, 2=Warning, 3=Info, 4=Hint "message": "Undefined method `foo' for OrderService", "range": { "start": {"line": 25, "character": 4}, "end": {"line": 25, "character": 7} }, "source": "solargraph" } ] }

Severity Levels:

• 1

• Error (must fix)

• 2

• Warning (should investigate)

• 3

• Information (good to know)

• 4

• Hint (suggestions)

2.4 rename_symbol

Rename a symbol across the codebase:

Preview changes (dry_run)

mcp__cclsp__rename_symbol( file_path: "app/models/user.rb", symbol_name: "full_name", new_name: "display_name", dry_run: true )

Apply changes

mcp__cclsp__rename_symbol( file_path: "app/models/user.rb", symbol_name: "full_name", new_name: "display_name" )

3. Interface Extraction Patterns

3.1 Extract Class Interface

Extract public interface from a class:

Pattern: Interface Extraction

def extract_interface(class_name, file_path)

1. Find class definition

definition = mcp__cclsp__find_definition( file_path: file_path, symbol_name: class_name, symbol_kind: "class" )

2. Read the class file

class_content = Read(definition.file)

3. Extract public methods

public_methods = class_content.scan(/^\s*def\s+(\w+)/).flatten

4. For each method, find references to understand usage

method_interfaces = public_methods.map do |method| refs = mcp__cclsp__find_references( file_path: definition.file, symbol_name: method )

{
  name: method,
  defined_at: "#{definition.file}:#{method_line}",
  usage_count: refs.count,
  callers: refs.map { |r| r.file }.uniq
}

end

method_interfaces end

3.2 Extract Dependency Graph

Build a dependency graph for a class:

Pattern: Dependency Graph

def build_dependency_graph(entry_class, entry_file) graph = { nodes: [], edges: [] } visited = Set.new queue = [[entry_class, entry_file]]

while queue.any? class_name, file_path = queue.shift next if visited.include?(class_name) visited.add(class_name)

# Add node
graph[:nodes] << { name: class_name, file: file_path }

# Find references to other classes
class_content = Read(file_path)
constants = class_content.scan(/([A-Z][A-Za-z0-9]+)/).flatten.uniq

constants.each do |const|
  definition = mcp__cclsp__find_definition(
    file_path: file_path,
    symbol_name: const,
    symbol_kind: "class"
  )

  if definition && !visited.include?(const)
    graph[:edges] << { from: class_name, to: const }
    queue << [const, definition.file]
  end
end

end

graph end

3.3 Per-Task Interface Extraction

Extract interfaces relevant to a specific task:

Pattern: Task-Specific Interface Extraction

def compile_task_context(task) context = { interfaces: [], vocabulary: [], cclsp_enhanced: true }

1. Identify files mentioned in task

target_files = task[:files] || []

2. For each file, extract interfaces

target_files.each do |file| # Get diagnostics first (validates file exists) diagnostics = mcp__cclsp__get_diagnostics(file_path: file)

# Find all symbols in file
symbols = extract_file_symbols(file)

# For each symbol, get definition and references
symbols.each do |symbol|
  definition = mcp__cclsp__find_definition(
    file_path: file,
    symbol_name: symbol[:name],
    symbol_kind: symbol[:kind]
  )

  references = mcp__cclsp__find_references(
    file_path: file,
    symbol_name: symbol[:name]
  )

  context[:interfaces] << {
    symbol: symbol[:name],
    kind: symbol[:kind],
    file: file,
    definition: definition,
    references: references.count,
    signature: extract_signature(definition)
  }
end

end

context end

4. Vocabulary Building Patterns

4.1 Project Vocabulary Extraction

Build a vocabulary of project-specific terms:

Pattern: Project Vocabulary

def build_project_vocabulary vocabulary = { models: [], services: [], controllers: [], patterns: [], domain_terms: [] }

1. Scan models

Dir["app/models/**/*.rb"].each do |file| content = Read(file)

# Extract class name
if content =~ /class\s+(\w+)/
  model_name = $1
  vocabulary[:models] << {
    name: model_name,
    file: file,
    associations: content.scan(/(?:has_many|belongs_to|has_one)\s+:(\w+)/).flatten,
    scopes: content.scan(/scope\s+:(\w+)/).flatten,
    validations: content.scan(/validates\s+:(\w+)/).flatten
  }
end

end

2. Scan services

Dir["app/services/**/*.rb"].each do |file| content = Read(file)

if content =~ /class\s+(\w+)/
  service_name = $1
  vocabulary[:services] << {
    name: service_name,
    file: file,
    public_methods: content.scan(/^\s*def\s+(\w+)/).flatten,
    dependencies: extract_dependencies(content)
  }
end

end

3. Extract domain terms from comments and names

all_files = Dir["app/**/*.rb"] all_files.each do |file| content = Read(file)

# Extract from comments
comments = content.scan(/#\s*(.+)$/).flatten

# Extract from class/method names
identifiers = content.scan(/(?:class|def|module)\s+(\w+)/).flatten

# Add unique terms
terms = (comments + identifiers).map(&:downcase).uniq
vocabulary[:domain_terms].concat(terms)

end

vocabulary[:domain_terms].uniq! vocabulary end

4.2 Symbol Vocabulary for Generation

Build vocabulary to guide code generation:

Pattern: Generation Vocabulary

def build_generation_vocabulary(target_file) vocab = { available_classes: [], available_methods: [], common_patterns: [], naming_conventions: [] }

1. Find all classes in the project

Dir["app/**/*.rb"].each do |file| content = Read(file) classes = content.scan(/class\s+(\w+)/).flatten vocab[:available_classes].concat(classes) end

2. For the target file's directory, find common patterns

dir = File.dirname(target_file) sibling_files = Dir["#{dir}/*.rb"]

sibling_files.each do |file| content = Read(file)

# Extract method patterns
methods = content.scan(/def\s+(\w+)/).flatten
vocab[:available_methods].concat(methods)

# Extract common patterns
if content.include?("Result.success")
  vocab[:common_patterns] << "Result monad"
end
if content.include?("ApplicationService")
  vocab[:common_patterns] << "ApplicationService inheritance"
end

end

vocab[:available_classes].uniq! vocab[:available_methods].uniq! vocab[:common_patterns].uniq!

vocab end

5. Guardian Validation Patterns

5.1 Pre-Generation Validation

Validate before generating code:

Pattern: Pre-Generation Check

def pre_generation_validate(target_file) validation = { passed: true, issues: [] }

1. Check if cclsp is available

begin mcp__cclsp__get_diagnostics(file_path: "Gemfile") rescue validation[:issues] << "cclsp not available - skipping LSP validation" return validation end

2. Check existing file for errors

if File.exist?(target_file) diagnostics = mcp__cclsp__get_diagnostics(file_path: target_file) errors = diagnostics.select { |d| d[:severity] == 1 }

if errors.any?
  validation[:passed] = false
  validation[:issues] << "Existing file has #{errors.count} errors - fix first"
end

end

3. Check parent class exists

(would need to parse generation template)

validation end

5.2 Post-Generation Validation (Guardian)

Validate after generating code:

Pattern: Guardian Validation

def guardian_validate(file_path) result = { passed: true, errors: [], warnings: [], suggestions: [] }

1. cclsp diagnostics (Solargraph)

diagnostics = mcp__cclsp__get_diagnostics(file_path: file_path)

diagnostics.each do |d| case d[:severity] when 1 # Error result[:passed] = false result[:errors] << { line: d[:range][:start][:line], message: d[:message], source: d[:source] } when 2 # Warning result[:warnings] << { line: d[:range][:start][:line], message: d[:message] } when 3, 4 # Info/Hint result[:suggestions] << { line: d[:range][:start][:line], message: d[:message] } end end

2. Sorbet type checking (if available)

sorbet_output = bundle exec srb tc #{file_path} 2>&1 sorbet_errors = sorbet_output.lines.select { |l| l.start_with?(file_path) }

sorbet_errors.each do |error| if error =~ /#{file_path}:(\d+):\s*(.+)/ result[:passed] = false result[:errors] << { line: $1.to_i, message: $2, source: "sorbet" } end end

result end

5.3 Generate-Validate-Execute-Verify Cycle

Full implementation cycle with Guardian:

Pattern: Full Implementation Cycle

def implement_with_guardian(file_path, specification, max_attempts: 3) attempt = 0

loop do attempt += 1 puts "Attempt #{attempt}/#{max_attempts}: #{file_path}"

# 1. GENERATE
puts "  1/4 GENERATE: Writing code..."
generate_code(file_path, specification)

# 2. VALIDATE (Guardian)
puts "  2/4 VALIDATE: Running Guardian..."
validation = guardian_validate(file_path)

unless validation[:passed]
  puts "  Guardian found #{validation[:errors].count} errors"

  if attempt >= max_attempts
    return { success: false, reason: "Max attempts reached" }
  end

  # Apply fixes and retry
  apply_guardian_fixes(file_path, validation[:errors])
  next
end

# 3. EXECUTE
puts "  3/4 EXECUTE: Running tests..."
test_result = run_tests_for_file(file_path)

unless test_result[:passed]
  puts "  Tests failed: #{test_result[:failures].count} failures"

  if attempt >= max_attempts
    return { success: false, reason: "Tests failed" }
  end

  # Analyze failures and retry
  analyze_and_fix_tests(file_path, test_result[:failures])
  next
end

# 4. VERIFY
puts "  4/4 VERIFY: Final check..."
final_check = final_verification(file_path)

return { success: true, attempts: attempt, verification: final_check }

end end

def apply_guardian_fixes(file_path, errors)

Group errors by type

undefined_methods = errors.select { |e| e[:message].include?("Undefined method") } type_errors = errors.select { |e| e[:source] == "sorbet" } syntax_errors = errors.select { |e| e[:message].include?("syntax") }

Apply targeted fixes

if undefined_methods.any? # Find correct method names using find_references fix_undefined_methods(file_path, undefined_methods) end

if type_errors.any? # Add type signatures or fix type mismatches fix_type_errors(file_path, type_errors) end

if syntax_errors.any? # Fix syntax issues fix_syntax_errors(file_path, syntax_errors) end end

6. Sorbet Integration Patterns

6.1 Type Signature Extraction

Extract Sorbet type signatures from a file:

Pattern: Sorbet Signature Extraction

def extract_sorbet_signatures(file_path) content = Read(file_path) signatures = []

Find sig blocks

content.scan(/sig\s*{([^}]+)}/) do |sig_content| sig = sig_content[0]

# Parse params
params = {}
sig.scan(/params\(([^)]+)\)/) do |params_str|
  params_str[0].split(",").each do |param|
    name, type = param.strip.split(":").map(&:strip)
    params[name] = type
  end
end

# Parse returns
returns = nil
if sig =~ /returns\(([^)]+)\)/
  returns = $1.strip
end

signatures << { params: params, returns: returns }

end

signatures end

6.2 Type-Guided Generation

Use type information to guide code generation:

Pattern: Type-Guided Generation

def generate_with_types(file_path, method_spec)

1. Look up existing type signatures in project

similar_methods = find_similar_methods(method_spec[:name])

2. Infer expected types from callers

references = mcp__cclsp__find_references( file_path: file_path, symbol_name: method_spec[:name] )

inferred_types = infer_types_from_usage(references)

3. Generate with explicit types

signature = <<~RUBY sig { params(#{format_params(inferred_types[:params])}).returns(#{inferred_types[:returns]}) } def #{method_spec[:name]}(#{format_args(method_spec[:args])}) # Implementation end RUBY

signature end

6.3 Sorbet Strictness Levels

Apply appropriate Sorbet strictness:

Pattern: Sorbet Strictness Selection

def select_sorbet_strictness(file_path)

New files: start with # typed: true

Critical business logic: use # typed: strict

Generated code: use # typed: false initially

case file_path when /app/services// "# typed: strict" # Services should have strong types when /app/models// "# typed: true" # Models can start with basic types when /app/controllers// "# typed: false" # Controllers often have complex types when /lib// "# typed: strict" # Library code should be well-typed else "# typed: true" # Default to basic type checking end end

7. Graceful Degradation

7.1 Tool Availability Check

Check which tools are available:

Pattern: Availability Check

check_tool_availability() { local availability="{}"

Check cclsp

if mcp__cclsp__get_diagnostics --file_path "Gemfile" 2>/dev/null; then availability=$(echo "$availability" | jq '.cclsp = true') else availability=$(echo "$availability" | jq '.cclsp = false') fi

Check Solargraph

if gem list solargraph -i &>/dev/null; then availability=$(echo "$availability" | jq '.solargraph = true') else availability=$(echo "$availability" | jq '.solargraph = false') fi

Check Sorbet

if bundle exec srb --version &>/dev/null || gem list sorbet -i &>/dev/null; then availability=$(echo "$availability" | jq '.sorbet = true') else availability=$(echo "$availability" | jq '.sorbet = false') fi

Check parser gem

if gem list parser -i &>/dev/null; then availability=$(echo "$availability" | jq '.parser = true') else availability=$(echo "$availability" | jq '.parser = false') fi

echo "$availability" }

7.2 Fallback Strategies

Fallback when tools are unavailable:

Pattern: Graceful Degradation

def compile_context_with_fallback(task) availability = check_tool_availability

context = { cclsp_enhanced: false, interfaces: [], vocabulary: [], fallback_used: [] }

Primary: Use cclsp

if availability[:cclsp] context[:cclsp_enhanced] = true context[:interfaces] = extract_interfaces_with_cclsp(task) else # Fallback: Use grep and AST parsing context[:fallback_used] << "grep for interface extraction" context[:interfaces] = extract_interfaces_with_grep(task) end

Primary: Use Sorbet for type info

if availability[:sorbet] context[:type_info] = extract_type_info_with_sorbet(task) else # Fallback: Use YARD comments context[:fallback_used] << "YARD for type hints" context[:type_info] = extract_type_info_from_yard(task) end

Primary: Use parser gem

if availability[:parser] context[:ast_analysis] = analyze_with_parser(task) else # Fallback: Use ripper (always available) context[:fallback_used] << "ripper for AST" context[:ast_analysis] = analyze_with_ripper(task) end

context end

def extract_interfaces_with_grep(task) interfaces = []

task[:files].each do |file| # Use grep to find method definitions methods = grep -n "def " #{file} | head -50.lines

methods.each do |line|
  if line =~ /^(\d+):\s*def\s+(\w+)/
    interfaces << {
      symbol: $2,
      kind: "method",
      file: file,
      line: $1.to_i
    }
  end
end

end

interfaces end

7.3 Partial Feature Mode

Enable features based on available tools:

Pattern: Feature Flags

def determine_enabled_features features = { lsp_diagnostics: false, type_checking: false, smart_refactoring: false, vocabulary_building: true, # Always available interface_extraction: true # Always available (grep fallback) }

availability = check_tool_availability

if availability[:cclsp] features[:lsp_diagnostics] = true features[:smart_refactoring] = true end

if availability[:sorbet] features[:type_checking] = true end

features end

8. Working Memory Integration

8.1 Store Compiled Context

Store context for implementation phase:

Pattern: Store Compiled Context

def store_compiled_context(task_id, context) memory_entry = { timestamp: Time.now.utc.iso8601, agent: "context-compiler", knowledge_type: "compiled_context", key: "task.#{task_id}.context", value: context, confidence: "verified" }

Write to working memory file

File.open(".claude/reactree-memory.jsonl", "a") do |f| f.puts(memory_entry.to_json) end end

8.2 Read Compiled Context

Read context during implementation:

Pattern: Read Compiled Context

def read_compiled_context(task_id) memory_file = ".claude/reactree-memory.jsonl" return nil unless File.exist?(memory_file)

Read most recent context for task

context = nil

File.readlines(memory_file).reverse_each do |line| entry = JSON.parse(line)

if entry["key"] == "task.#{task_id}.context"
  context = entry["value"]
  break
end

end

context end

9. Quick Reference

Command Cheatsheet

Solargraph

gem install solargraph solargraph config # Generate .solargraph.yml solargraph socket --port 7658 # Start language server

Sorbet

gem install sorbet sorbet-runtime bundle exec srb init # Initialize Sorbet bundle exec srb tc # Type check project bundle exec srb tc app/models/ # Type check directory bundle exec srb tc --ignore=sorbet/ # Ignore directory

Tapioca (RBI generation)

gem install tapioca bundle exec tapioca init # Initialize bundle exec tapioca gems # Generate gem RBIs bundle exec tapioca dsl # Generate DSL RBIs bundle exec tapioca annotations # Sync annotations

parser gem

gem install parser ruby -rparser/current -e 'p Parser::CurrentRuby.parse("def foo; end")'

cclsp MCP Quick Reference

Find where a method is defined

mcp__cclsp__find_definition( file_path: "app/models/user.rb", symbol_name: "authenticate" )

Find all usages of a class

mcp__cclsp__find_references( file_path: "app/services/payment_service.rb", symbol_name: "PaymentService" )

Check file for errors

mcp__cclsp__get_diagnostics( file_path: "app/services/order_service.rb" )

Rename symbol (preview)

mcp__cclsp__rename_symbol( file_path: "app/models/user.rb", symbol_name: "old_method", new_name: "new_method", dry_run: true )

Guardian Validation Quick Reference

Full validation cycle

def validate_file(file_path)

1. cclsp diagnostics

diagnostics = mcp__cclsp__get_diagnostics(file_path: file_path) errors = diagnostics.select { |d| d[:severity] == 1 }

2. Sorbet check

sorbet_output = bundle exec srb tc #{file_path} 2>&1 sorbet_errors = sorbet_output.lines.count { |l| l.start_with?(file_path) }

3. Combined result

{ passed: errors.empty? && sorbet_errors == 0, lsp_errors: errors.count, sorbet_errors: sorbet_errors } end