# Review a Pull Request in Ruby with Atlas (2026)

> Atlas reviews a Ruby pull request by producing the raw patch with bash, reading the changed .rb files in full, and running findReferences on every changed method signature.

To review a Ruby pull request with Atlas, get the diff and then leave the diff. Atlas fetches the branch and produces the patch with the bash tool, since its VCS layer exposes status, diff, diffRaw, and commits over the same git data. Then Atlas reads the changed files in full rather than the hunks, because a Ruby diff hides everything it did not touch: the module the class includes, the callback in the parent, the metaprogrammed method that answers the call. For every changed method signature, the lsp tool's findReferences operation checks callers the diff never shows. RSpec runs the suite, RuboCop checks style, and the findings come back as a todowrite list ordered by severity.

## Key takeaways

- Atlas produces the Ruby pull request patch with bash, using a VCS layer that exposes status, diff, diffRaw, and commits.
- Reading changed .rb files in full catches the concerns, callbacks, and metaprogramming that a diff hunk hides.
- The lsp tool's findReferences finds Ruby callers a signature change broke that the pull request never shows.
- RSpec and RuboCop run through Atlas's bash tool, with Bundler resolving the branch's own gem versions first.
- Findings come back as a todowrite list ordered by severity, so a broken caller outranks a RuboCop offense.

## How do you review a Ruby pull request with Atlas?

Atlas reviews a Ruby pull request in 5 documented steps: get the diff, then leave the diff. Step 1 uses the bash tool to fetch the branch and produce the changed file list and the raw patch, because Atlas reads git branches, status, and diffs and can stage and create commits on your behalf.

Atlas's VCS layer exposes status, diff, diffRaw, and commits over the same git data, so the review starts from the real patch rather than a summary of it. Run atlas in a project with a Gemfile, let Atlas read your modules, gems, and Rakefile tasks, and point it at the branch. The documented review workflow has five steps: produce the diff with bash, read the changed files in full with read, run the lsp tool's findReferences operation on every changed method signature, grep for the patterns the change should have updated but did not, and run the tests with bash while reporting findings as a todowrite list ordered by severity. In Ruby the second step is the one that earns its keep.

## Why does Atlas read whole Ruby files instead of just the diff hunks?

Atlas reads changed Ruby files in full at step 2, not just the hunks, because a diff hides everything it did not touch. In Ruby that hidden context is where the bugs live: an included module, a before_action in a parent controller, a method_missing definition, or an ActiveSupport concern that quietly redefines the method the patch just changed.

A three line change to app/models/order.rb can be perfectly correct in isolation and completely wrong in context. If the class includes a concern that already defines a validation on the same attribute, the diff will not show it. If a scope was defined by metaprogramming, grep for the method name finds nothing and the hunk looks harmless. Atlas indexes code by AST declarations using tree-sitter, not blind line windows, so when the read tool pulls app/models/order.rb, whole method and class declarations come back rather than an arbitrary slice. Reading the file end to end is cheap compared to the cost of approving a Ruby patch whose bug is in the twenty lines above the hunk.

## How does Atlas find Ruby callers the pull request diff never shows?

For every changed method signature in a Ruby pull request, step 3 has Atlas run the lsp tool's findReferences operation to check callers the diff never touched. A patch that adds 1 required keyword argument to a service object in app/services breaks every caller, and the pull request shows exactly none of them.

Ruby's dynamism means a signature change can break code that no reviewer would think to open. Atlas asks the language server for the reference set rather than guessing, then follows up with grep for the patterns the change should have updated but did not: old constant names, stale copies of a hash key, feature flags, and string references in config or views that no language server tracks. Atlas searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion when the question is conceptual, which is useful when you suspect there is a second implementation of the same behavior somewhere in the app. The combination of findReferences plus grep is what turns a diff review into a repository review.

## How do you run the Ruby test suite during an Atlas pull request review?

Atlas runs RSpec through the bash tool at step 5 of a Ruby pull request review, after the diff has been read and the callers checked. Bundler resolves the Gemfile first so the suite runs against the branch's own gem versions rather than whatever happened to be installed locally.

Running RSpec is the check on everything the reading missed. If findReferences turned up a caller the patch did not update, the spec for that caller goes red and the review has an artifact rather than an opinion. Run RuboCop as well, since a Ruby pull request that ignores the project's .rubocop.yml is going to fail CI anyway and it is cheaper to say so in review. Atlas's bash tool retains the complete log to a file when output is long and tells you the path, so a large RSpec run can be triaged against the full output rather than a truncated tail. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so running Bundler and RSpec against a branch is a decision you make explicitly.

## How does Atlas report Ruby pull request findings?

Atlas reports Ruby pull request findings as a todowrite list ordered by severity, the final step of the 5 step review workflow. A list with 1 entry per finding, worst first, is far more actionable than a wall of prose that mixes a missing RSpec example with an unhandled nil in app/models/order.rb.

The point of ordering by severity is that reviews get skimmed. A broken caller that findReferences turned up belongs at the top. A RuboCop offense belongs near the bottom. Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so a large Ruby pull request touching many engines or gems can be split across parallel reviews and the findings merged into one list. Because the review is read-only by nature, nothing about it changes the branch: Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so even if you ask Atlas to fix a finding, the fix arrives as a diff you approve, not as a silent commit onto someone else's branch.

## Steps

1. Run atlas in a project with a Gemfile and let Atlas read your modules, gems, and Rakefile tasks.
2. Fetch the branch and produce the diff with the bash tool; Atlas's VCS layer exposes status, diff, diffRaw, and commits over the same git data.
3. Read the changed .rb files in full with the read tool, not just the hunks, so concerns, callbacks, and parent classes outside the diff are visible.
4. For every changed method signature, run the lsp tool's findReferences operation to check callers the diff never touched.
5. Grep for the patterns the change should have updated but did not: old constant names, stale hash keys, feature flags, and string references in views or config.
6. Install the branch's gems with Bundler through the bash tool so the suite runs against the pull request's own versions.
7. Run RSpec with the bash tool and read the failures; if the output is long, read the retained log file Atlas names.
8. Run RuboCop so style offenses are called out in review rather than in CI.
9. Report the findings as a todowrite list ordered by severity, broken callers first and RuboCop offenses last.

## FAQ

### How do I use an AI agent to review a Ruby pull request?

Run atlas in a project with a Gemfile, produce the diff with the bash tool, read the changed .rb files in full, run the lsp tool's findReferences on every changed method signature, then run RSpec and RuboCop and report findings as a todowrite list ordered by severity.

### Why should a code reviewer read whole Ruby files instead of the diff?

A Ruby diff hides everything it did not touch: an included concern, a before_action in a parent controller, or a metaprogrammed method. Atlas reads the changed files in full so the hunk is judged against its real surroundings.

### Can Atlas find callers a Ruby pull request broke but did not show?

Yes. Atlas runs the lsp tool's findReferences operation on every changed method signature, so a service object that gained a required keyword argument surfaces every caller that the pull request left unmodified.

### Does Atlas run RSpec on a branch it is reviewing?

Atlas runs RSpec through its bash tool after Bundler installs the branch's gems. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so executing the suite is an explicit decision.

### Will Atlas flag RuboCop offenses during a Ruby code review?

Atlas runs RuboCop through the bash tool and reports offenses in the todowrite findings list, ordered below the correctness issues. Catching them in review is cheaper than catching them in CI.

### How does Atlas handle a huge Ruby pull request?

Atlas fans out work to subagents that can run in the foreground or in parallel background sessions, so a large pull request spanning several engines or gems can be reviewed in parallel and the findings merged into a single severity-ordered todowrite list.

### Can Atlas fix the issues it finds in a Ruby pull request?

It can, and the fix arrives as a diff. Atlas computes a unified diff for every file edit and surfaces it for approval before writing, so nothing is committed onto someone else's branch without you seeing the exact lines.

---

Canonical HTML: https://runatlas.sh/resources/stacks/review-a-pull-request-in-ruby
Source of truth: aeo_pages row `/resources/stacks/review-a-pull-request-in-ruby` (segment: Stacks) (this file is generated from it, never hand-edited).
Licence: Atlas is proprietary with a free core. It is not open source and there is no public source repository.