fix-rubocop
Fixes RuboCop offenses systematically and safely. Use when the user wants to reduce RuboCop warnings, clean up .rubocop_todo.yml, fix linting errors, or improve code style compliance.
When & Why to Use This Skill
The fix-rubocop skill is a specialized automation tool designed to systematically identify and resolve RuboCop offenses in Ruby codebases. It streamlines the process of maintaining code quality by prioritizing safe autocorrects, managing .rubocop_todo.yml files through proper regeneration, and ensuring all style improvements are verified against existing test suites. This skill is essential for developers looking to enforce idiomatic Ruby standards and reduce technical debt with minimal manual intervention.
Use Cases
- Legacy Code Cleanup: Systematically reducing the number of offenses in a large .rubocop_todo.yml file by targeting specific cops one at a time.
- Pre-PR Refactoring: Automatically fixing stylistic inconsistencies and linting errors in newly developed features before submitting a Pull Request.
- Global Style Updates: Applying codebase-wide changes for specific rules, such as converting string literals or updating hash syntax, while ensuring functional integrity.
- Continuous Integration Support: Assisting developers in quickly resolving linting failures caught by CI pipelines by providing safe, automated fixes and test verification.
| name | fix-rubocop |
|---|---|
| description | Fixes RuboCop offenses systematically and safely. Use when the user wants to reduce RuboCop warnings, clean up .rubocop_todo.yml, fix linting errors, or improve code style compliance. |
| allowed-tools | [Bash, Read, Edit, Grep] |
Fix RuboCop Violations Skill
Assists with systematically reducing RuboCop offenses while preserving behavior and keeping changes focused.
IMPORTANT: When using this skill, announce to the user: "Using fix-rubocop skill to fix RuboCop violations systematically."
Goals
- Keep changes minimal and behavior-preserving: Prefer small, focused changes
- Use safe autocorrect first: Apply unsafe corrections only when reviewed and covered by tests
- Centralize rule changes in
.rubocop.yml: Never hand-edit.rubocop_todo.yml - No inline disables: This project forbids
# rubocop:disablecomments
Quick Reference Commands
# Full lint check
rake rubocop
# Lint specific file or directory
bundle exec rubocop path/to/file.rb
# Safe autocorrect (recommended first step)
bundle exec rubocop -a path/to/file.rb
# Unsafe autocorrect for specific cop (use with caution)
bundle exec rubocop -A --only Cop/Name path/to/file.rb
# Run tests to verify no behavior changes
rake spec
# Regenerate .rubocop_todo.yml after fixes
bundle exec docquet regenerate-todo
Complete Workflow
Step 1: Reproduce and Identify Offenses
# Run full lint to see all offenses
rake rubocop
# Note the failing cops and affected files
# Example output:
# lib/foxtail/formatter.rb:15:3: C: Style/StringLiterals: ...
Identify the scope:
- Which cop(s) are failing?
- Which file(s) are affected?
- How many offenses?
Step 2: Safe Autocorrect First
Start with the safest approach - automatic fixes that preserve behavior:
# Target specific files to reduce blast radius
bundle exec rubocop -a lib/foxtail/specific_file.rb
# Or target a directory
bundle exec rubocop -a lib/foxtail/
# Verify no new failures
rake rubocop
# CRITICAL: Verify tests still pass
rake spec
If tests fail after autocorrect:
- Revert changes:
git checkout lib/foxtail/specific_file.rb - Proceed to Step 3 for manual fixes
Step 3: Target Specific Cops (If Still Failing)
For remaining offenses, fix specific cops one at a time:
# For stylistic issues
bundle exec rubocop -A --only Style/StringLiterals lib/foxtail/
# For performance issues (manual review recommended)
bundle exec rubocop --only Performance/MapCompact lib/foxtail/
# Review and fix manually based on suggestions
# Verify after each cop
rake rubocop
rake spec
Important: For logic-sensitive cops (Performance, Lint), prefer manual fixes with test verification.
Step 3a: Fixing Cops Disabled in .rubocop_todo.yml
If a cop is disabled in .rubocop_todo.yml, you must temporarily enable it:
# 1. Check if cop is in TODO file
grep -A 5 "Cop/Name" .rubocop_todo.yml
# 2. Temporarily comment out that cop's block in .rubocop_todo.yml
# (RuboCop respects TODO disables even with --only)
# 3. Run targeted fix
bundle exec rubocop --only Cop/Name path/to/file.rb
# or with autocorrect:
bundle exec rubocop -A --only Cop/Name path/to/file.rb
# 4. Validate changes
rake rubocop
rake spec
# 5. Regenerate TODO file (removes fixed cops automatically)
bundle exec docquet regenerate-todo
# 6. Commit code changes AND regenerated .rubocop_todo.yml together
CRITICAL: Always use docquet regenerate-todo to update the TODO file. Never edit it manually.
Step 4: Update Configuration (Rare)
If a rule conflicts with project style:
# Edit .rubocop.yml to adjust the rule
# Add clear comment explaining the rationale
Example in .rubocop.yml:
# We prefer double quotes for consistency with string interpolation
Style/StringLiterals:
EnforcedStyle: double_quotes
After configuration changes:
# Regenerate TODO to reflect new config
bundle exec docquet regenerate-todo
# Verify
rake rubocop
Step 5: No Inline Disables
FORBIDDEN:
# ❌ NEVER do this
def some_method
# rubocop:disable Style/SomeCop
code_here
# rubocop:enable Style/SomeCop
end
If a finding cannot be safely fixed:
- Ask the user for guidance
- Options:
- Refine the rule in
.rubocop.yml - Adjust the code approach
- Document why this specific pattern is needed
- Refine the rule in
Step 6: Validate and Commit
# Ensure everything is clean
rake
# Should show:
# - All tests passing
# - No RuboCop offenses (or reduced offenses)
Commit message format:
cat > /tmp/commit_msg.txt <<'EOF'
:police_officer: Fix Style/StringLiterals violations in lib/foxtail
Convert single quotes to double quotes for consistency.
EOF
git commit -F /tmp/commit_msg.txt
rm /tmp/commit_msg.txt
Commit message patterns:
:police_officer:- All RuboCop fixes (style, lint, performance):wrench:- Update RuboCop configuration
Common Scenarios
Scenario 1: Reduce .rubocop_todo.yml Violations
# 1. Check current state
cat .rubocop_todo.yml
# Note: List of disabled cops and offense counts
# 2. Pick one cop to fix (start with lowest count)
# Example: Style/CommentedKeyword (1 offense)
# 3. Find affected files
bundle exec rubocop --only Style/CommentedKeyword
# 4. Apply fix
bundle exec rubocop -A --only Style/CommentedKeyword lib/foxtail/
# 5. Verify
rake spec
rake rubocop
# 6. Regenerate TODO
bundle exec docquet regenerate-todo
# The fixed cop should be removed automatically
# 7. Commit
git add .
git commit -m ":police_officer: Fix Style/CommentedKeyword violations"
Scenario 2: Fix All Offenses in One File
# 1. Target specific file
bundle exec rubocop lib/foxtail/date_time_format.rb
# 2. Safe autocorrect first
bundle exec rubocop -a lib/foxtail/date_time_format.rb
# 3. Check remaining offenses
bundle exec rubocop lib/foxtail/date_time_format.rb
# 4. Fix remaining manually or with targeted cops
bundle exec rubocop -A --only Naming/VariableNumber lib/foxtail/date_time_format.rb
# 5. Verify
rake spec
# 6. If cop was in TODO, regenerate
bundle exec docquet regenerate-todo
# 7. Commit
git commit -m ":police_officer: Fix all RuboCop violations in date_time_format.rb"
Scenario 3: Fix Specific Cop Across Entire Codebase
# 1. Check scope
bundle exec rubocop --only Style/StringLiterals
# Shows all files and offense counts
# 2. Start with smallest files or directories
bundle exec rubocop -A --only Style/StringLiterals lib/foxtail/helpers/
# 3. Verify incrementally
rake spec
git add lib/foxtail/helpers/
git commit -m ":police_officer: Fix Style/StringLiterals in helpers"
# 4. Continue with other directories
bundle exec rubocop -A --only Style/StringLiterals lib/foxtail/models/
rake spec
git commit -m ":police_officer: Fix Style/StringLiterals in models"
# 5. Final regenerate
bundle exec docquet regenerate-todo
git commit -m ":wrench: Regenerate RuboCop TODO after fixes"
Examples by Cop Type
Style Cops (Usually Safe)
# String literals
bundle exec rubocop -A --only Style/StringLiterals lib/
# Hash syntax
bundle exec rubocop -A --only Style/HashSyntax lib/
# Frozen string literals
bundle exec rubocop -A --only Style/FrozenStringLiteralComment lib/
Naming Cops (May Need Review)
# Variable naming
bundle exec rubocop -A --only Naming/VariableNumber lib/foxtail/file.rb
# Method naming (often requires manual decision)
bundle exec rubocop --only Naming/PredicateMethod lib/foxtail/file.rb
# Review output and fix manually:
# - Either rename method to end with ?
# - Or document why it shouldn't be a predicate
Lint Cops (Require Careful Review)
# Unused variables (manual fix recommended)
bundle exec rubocop --only Lint/UnusedMethodArgument lib/
# Review each and either use or prefix with _
# Verify with tests
rake spec
Performance Cops (Test Thoroughly)
# Performance improvements (review before applying)
bundle exec rubocop --only Performance/MapCompact lib/
# Apply manually to ensure behavior preservation
# ALWAYS run full test suite
rake spec
Common Pitfalls to Avoid
- Don't run unsafe autocorrect on entire codebase: Use
-Aon small scopes only - Don't skip test verification: Always run
rake specafter fixes - Don't manually edit .rubocop_todo.yml: Always use
docquet regenerate-todo - Don't use inline disables: This project forbids
# rubocop:disablecomments - Don't commit without regenerating TODO: If fixing TODO cops, always regenerate
- Don't mix unrelated fixes: Keep commits focused on one cop or one area
- Don't ignore test failures: Revert and fix manually if tests fail after autocorrect
Troubleshooting
Issue: Cop not showing offenses despite being in .rubocop_todo.yml
Problem: Cop is disabled in TODO file
Solution:
# Temporarily comment out the cop in .rubocop_todo.yml
# Then run:
bundle exec rubocop --only Cop/Name
# After fixing, regenerate TODO
bundle exec docquet regenerate-todo
Issue: Tests fail after autocorrect
Problem: Unsafe autocorrect changed behavior
Solution:
# Revert changes
git checkout path/to/file.rb
# Fix manually or use safer approach
bundle exec rubocop --only Cop/Name path/to/file.rb
# Review suggestions and fix by hand
# Verify each change
rake spec
Issue: docquet regenerate-todo not working
Problem: Command not found or gem not installed
Solution:
# Ensure bundler is up to date
bundle install
# Check if docquet is installed
bundle exec docquet --version
# If not, check Gemfile and install dependencies
Issue: Too many offenses to fix at once
Problem: Overwhelming number of violations
Solution:
- Pick ONE cop type to fix
- Start with lowest offense count
- Fix incrementally, one file/directory at a time
- Commit after each successful fix
- Use PR per cop type or per area
PR Guidance
Keep changes small and single-purpose:
- Good: "Fix Style/StringLiterals in lib/foxtail/formatters"
- Bad: "Fix multiple RuboCop issues across codebase"
Include context in PR body:
## Summary
Fix Style/StringLiterals violations in formatter classes
## Changes
- Convert single quotes to double quotes in 5 files
- Applied safe autocorrect (-a flag)
## Verification
- All tests pass (rake spec)
- RuboCop clean for these files
- Regenerated .rubocop_todo.yml
Link rule changes to rationale:
If updating .rubocop.yml, explain why in PR description.
Best Practices
- Start with safe autocorrect: Use
-abefore-A - Small, focused PRs: One cop type or one directory at a time
- Test after every change: Run
rake specfrequently - Regenerate TODO incrementally: After fixing each cop type
- Commit incrementally: Don't wait to fix everything before committing
- Document decisions: If excluding a cop, explain why in
.rubocop.yml - Review Performance/Lint changes: Don't blindly autocorrect these
- Keep blast radius small: Target specific files/directories when possible