---
name: ruby-lsp
description: Ruby and Rails semantic code assistance using Ruby LSP tools. Use when editing Ruby, Rails, Rake, Gemfile, or related test files.
---

# Ruby LSP Workflow

Use this skill when working in Ruby or Rails repositories.

## Workflow

1. Prefer Ruby LSP tools over text search for semantic questions.
2. Before large refactors, inspect file structure with `ruby_lsp_symbols`.
3. For definition questions, use `ruby_lsp_definition`.
4. For API/context questions at a cursor position, use `ruby_lsp_hover`.
5. For symbol renames, prefer `ruby_lsp_rename` over manual multi-file edits. Preview first (`apply: false`) unless the user explicitly asked to apply.
6. For formatting, use `ruby_lsp_format`; it previews by default and writes only with `apply: true`.
7. For diagnostic quick fixes/refactors, use `ruby_lsp_code_actions` before hand-editing.
8. In Rails apps or engines, use `ruby_lsp_rails_routes` to inspect routes instead of discovering route commands manually; v1.0 resolves the selected Ruby/Rails root for nested apps and monorepos.
9. After editing `.rb`, `.rake`, `Gemfile`, or Rails files, auto-diagnostics should refresh in the status line; run `ruby_lsp_diagnostics` manually when you need full diagnostic JSON or the status is unclear.
10. If Ruby LSP is unavailable, fall back to project checks such as:
   - `bundle exec ruby -c <file>`
   - `bundle exec rubocop <file>`
   - project test commands from README, AGENTS.md, or CI config

Do not claim Ruby code is complete until diagnostics or relevant tests have been checked, unless the user explicitly asks to skip validation.

## Cursor positions

Ruby LSP tools use zero-based line and character positions, matching the Language Server Protocol.

## Setup expectations

The selected Ruby root should provide Ruby LSP via either:

```bash
bundle exec ruby-lsp
```

or:

```bash
ruby-lsp
```

For monorepos, the extension walks upward from the target file and chooses the most specific Ruby root with markers such as `Gemfile`, `bin/rails`, `config/routes.rb`, or `*.gemspec`. If neither Bundler nor global Ruby LSP works, run `ruby_lsp_doctor` and follow its `errorInfo.suggestions`, or ask the user whether to install `ruby-lsp` or continue with fallback shell checks.