To debug a single failing test in Ruby, Atlas runs that one example in isolation with the bash tool, using RSpec's filter flag so the output stays small enough to reason about. Atlas then reads the spec and the class it exercises, walks the call path with the lsp tool's goToDefinition and findReferences operations, and only then edits. The goal is to fix the code, not the assertion, and the full Bundler-managed suite proves it.
How does Atlas debug one failing RSpec example in Ruby?
Atlas debugs a failing Ruby test by running exactly 1 example through the bash tool, using RSpec's filter flag so the output is small enough to reason about. Atlas reads the spec under spec/, walks the call path with the lsp tool, and then edits the class rather than the expectation.
A full Ruby suite run buries one red example in thousands of lines. Atlas narrows first: bash is a real shell, so the same levers you would reach for by hand are available, including a focused RSpec filter and a verbose flag. Because Atlas indexes code by AST declarations using tree-sitter, not blind line windows, the class under test in app/ or lib/ is retrieved as a declaration rather than an arbitrary slice of lines. The read tool then pulls the spec file and the module it exercises so both sides of the failure are in context at once.
How do I run a single RSpec spec file or line with Atlas?
Atlas runs 1 Ruby example at a time through bash with RSpec's filter, for example bundle exec rspec spec/models/invoice_spec.rb:42, which executes only the example on that line. Bundler resolves the gems from your Gemfile, so the spec runs against exactly the dependency set your full suite uses.
Isolation is the first real step of the workflow. Running one spec file under Bundler keeps the failure output to a single expectation, a single backtrace, and the lines of Ruby that produced it. Atlas captures that output through the bash tool, which is a real shell, so nothing about the RSpec invocation is special-cased or simulated. If the failure needs more detail, Atlas re-runs with a verbose flag through bash rather than guessing, because the cheapest way to test a hypothesis about a Ruby object is usually to print it.
How does Atlas trace a Ruby failure back to the class that causes it?
Atlas walks the Ruby call path with 2 lsp operations, goToDefinition and findReferences, jumping from the failing RSpec expectation into the method in app/ or lib/ that produced the wrong value. Reading the spec and the class together is what separates a real diagnosis from a guess.
Ruby's dynamism is exactly why a symbol graph helps: a method call in a spec can land in a module, a concern, or a superclass, and grep alone will show all three without ranking them. The lsp tool's goToDefinition takes Atlas to the definition actually in play, and findReferences enumerates every other caller of that method, which is how a fix gets checked for blast radius before it is written. Atlas also searches code with hybrid semantic and keyword retrieval fused by reciprocal rank fusion, so a behavior described in plain words still resolves to the right Ruby method.
How does Atlas test a hypothesis before changing Ruby code?
Atlas tests a hypothesis about a failing Ruby spec with 2 cheap moves: adding temporary logging through the edit tool, or re-running the RSpec example with a verbose flag through bash. Both are reversible, because Atlas snapshots file changes as git patches, so temporary logging is trivially removed before the commit.
Guessing is the expensive failure mode in debugging. Atlas commits to a hypothesis, then checks it: a puts or a logger line dropped into the Ruby method with edit, or a more verbose RSpec run through bash. Because Atlas computes a unified diff for every file edit and surfaces it for approval before writing, even a throwaway logging line is visible before it lands. Once the hypothesis is confirmed, the temporary lines come out, and the git patch snapshot makes it easy to confirm none survived into the commit.
How does Atlas apply the fix and prove the Ruby suite is still green?
Atlas fixes the Ruby production code with edit, or with apply_patch when the change spans several hunks, then proves the result with 2 bash runs: the single RSpec example first, then the full suite. RuboCop keeps the diff clean, and Bundler ensures both runs use the gems your Gemfile pins.
Chaining brittle edits across a long Ruby class is how a refactor goes wrong, which is why a multi-hunk change goes through apply_patch instead. Every Atlas tool call is permission-gated against allow, ask, and deny rules before it runs, so the bash calls that run RSpec and the edits that touch app/ or lib/ each pass the same check. After the single example is green, Atlas runs the full suite to catch collateral damage, removes any temporary logging it added, and runs RuboCop so the commit shows the behavior change rather than style noise.
Step by step
- 01Run atlas in a Ruby project with a Gemfile and let Atlas read your modules, gems, and Rakefile tasks.
- 02Run just the failing example with bash, using RSpec's filter flag, for example bundle exec rspec spec/models/invoice_spec.rb, so the output stays small.
- 03Read the spec and the class it exercises with the read tool, then use the lsp tool's goToDefinition and findReferences operations to walk the call path.
- 04Form a hypothesis and check it: add temporary logging to the Ruby method with edit, or re-run the RSpec example with a verbose flag through bash.
- 05Fix the production code in app/ or lib/ with edit; if the change spans several hunks, use apply_patch instead of chaining brittle edits.
- 06Re-run the single RSpec example with bash, then run the full Bundler-managed suite.
- 07Remove any temporary logging you added and run RuboCop over the touched Ruby files.
Frequently asked questions
- how to debug a failing rspec test with an AI agent
- Have Atlas run the single example through bash with RSpec's filter flag, read the spec and the class it exercises, then walk the call path with the lsp tool's goToDefinition before editing anything.
- can atlas run bundle exec rspec on just one spec file
- Yes. Atlas's bash tool is a real shell, so it runs the RSpec filter you would type by hand, for example bundle exec rspec spec/models/invoice_spec.rb, and captures the output for reasoning.
- how do i stop an AI from fixing the assertion instead of the ruby bug
- Atlas reads the spec and the class it exercises before editing, and uses the lsp tool to trace which Ruby method produced the wrong value. The fix lands in app/ or lib/, and Atlas surfaces the unified diff for approval.
- does atlas understand ruby modules and concerns
- Atlas indexes code by AST declarations using tree-sitter, not blind line windows, and uses the lsp tool's goToDefinition to resolve which module, concern, or superclass a Ruby call actually reaches.
- what does atlas need to work in a ruby project
- Run atlas in a project with a Gemfile. Atlas reads your modules, gems, and Rakefile tasks, then can write RSpec examples or extract a module, showing the diff before it writes.
- when should atlas use apply_patch instead of edit in ruby
- Use apply_patch when the Ruby fix spans several hunks in the same file. Chaining brittle edits across a long class is fragile, and apply_patch applies the whole structural change as one reviewable patch.
- does atlas run rubocop after fixing a ruby test
- Atlas can run RuboCop through its bash tool over the files it touched, which keeps the commit diff focused on the behavior fix rather than formatting churn.
Try Atlas in your terminal
The terminal-native AI coding agent. Free core, single binary.
Install AtlasRelated guides
Debug a Single Failing Test with Atlas in 2026
How to debug one failing test with Atlas in 2026: run it in isolation with bash, walk the call graph with the lsp tool, and fix the code, not the assertion.
Research a Third-Party API Before Integrating It in Ruby with Atlas (2026)
Pull a third-party API's real shape into context before you write Ruby. Atlas uses websearch and webfetch in 2026, then RSpec and Bundler prove the integration.
Trace a Runtime Bug From a Stack Trace in Ruby with Atlas (2026)
How to go from a Ruby backtrace to the responsible line with Atlas in 2026: read each frame at its offset, grep the error string, walk callers, then lock it with RSpec.
Diagnose a hanging or long-running command in Ruby with Atlas (2026)
How Atlas diagnoses a hanging or long-running Ruby command in 2026: read the shell_metadata block, tell a blocked Bundler prompt from a genuinely slow RSpec run.
Onboard to an Unfamiliar Ruby Codebase with Atlas in 2026
Build a mental model of an unfamiliar Ruby repo in 2026 without reading every file: Atlas uses codebase_search, glob, and a read-only explore subagent on your Gemfile project.
Write unit tests for untested code in Ruby with Atlas (2026)
Add RSpec coverage to an untested Ruby module in 2026 with Atlas: enumerate methods with lsp documentSymbol, copy the repo's spec conventions, then run the suite.
Plan a multi-file change before editing in Ruby with Atlas (2026)
How Atlas plans a multi-file Ruby change before editing: the read-only plan agent, .atlas/plans/*.md, plan_exit, and a Bundler, RSpec, RuboCop workflow.
Run Atlas Headless in CI for Ruby Projects in 2026
Automate Atlas in your Ruby CI/CD pipelines by 2026. Get machine-readable output for RSpec, Bundler, and RuboCop tasks, ensuring safe, non-interactive code generation.