renseiai/donmai-kits/ruby-debugging

Ruby Debugging

Overview

Debugging Ruby load errors, Bundler resolution problems, rubocop offenses, and spec failures. Systematic diagnosis for the most common Ruby/Bundler failure modes.

Triggers

Use this skill when:

• bundle install fails to resolve gems
• bundle exec rspec fails, errors on load, or hangs
• bundle exec rubocop reports offenses that block validate
• LoadError / cannot load such file at require time

Debugging Workflow

1. Bundler / Gem Resolution

bundle install 2>&1 | head -40

Common root causes:

• Version conflicts in Gemfile.lock — bundle update <gem> for the conflicting

dependency, or relax the constraint in the Gemfile

• Native-extension build failure — a missing system library/header
• Wrong Ruby version — check .ruby-version vs the active rbenv version

(rbenv version)

2. Load Errors

ruby -e "require './lib/<file>'" 2>&1 | head -20

Common root causes:

• require vs require_relative mismatch
• File not on the load path — run via bundle exec so the gem's lib/ is loaded
• Missing gem — add it to the Gemfile and bundle install

3. Rubocop (validate gate)

bundle exec rubocop 2>&1 | tail -30

Most offenses are auto-correctable: bundle exec rubocop -A (safe) / -a (autocorrect). Prefer fixing over inline # rubocop:disable.

4. Spec Failures

bundle exec rspec 2>&1 | grep -E "Failure|Error|examples" | head -30

Common root causes:

• Shared mutable state across examples — reset in before/after hooks
• Stubbed/mocked methods drifting from the real API
• Flaky tests depending on example ordering (--order random surfaces these)

Notes

• rbenv shims live in ~/.rbenv/shims. If ruby/bundle are not found, run

eval "$(rbenv init - bash)" first (the installer set rbenv up there).

• Always invoke tools through bundle exec to use the locked gem versions.