rubocop-kata

A RuboCop plugin that replaces a pile of linter gems and config with one dependency. Install it and your .rubocop.yml shrinks to project-specific overrides. Everything else comes from the gem: a curated stack of RuboCop extensions, opinionated style defaults, and thirty-seven house cops, ten of which wait in an opt-in strict Elegant Objects profile.

Kata's naming and size rules began as Elegant Objects' one-word names and five-line methods. We measured them and they moved. In a blind readability study, two samples each held 30 entry methods (with their same-class helpers) from kimera and hashira, two codebases written to kata's rules, and 30 from rubocop, faraday and rubygems.org. Each sample was rated by two independent AI reviewers (separate model instances that saw only the code, shuffled, with no source names), who agreed on 54 and 55 of 60 calls; no human has rated it yet. Readers judged 14–16 of the 30 house-style items over-fragmented, against 0–2 of 30 in the control. They scored readability about 3.0 against 4.0 and name clarity about 2.5 against 4.1, calling the one-word names vague or metaphorical (rolls, homes, sightings, pinpoint). House-style methods averaged 3.0 lines, the control 6.3. The study cannot separate the rules from the people who followed them, but it points one way, and the defaults followed:

• Methods may run to RuboCop's 10 lines. Logic density is what is bounded, by Metrics/AbcSize 17, CyclomaticComplexity 7 and PerceivedComplexity 8.
• Names may take two words (parse_header, line_items), not counting role words (after_fork, file_of). Three or more words still fail, and so do chained actions (validate_and_save). Kata/RealWords still fails a smash (matchingids) and a clipping (cfg). MaxWords: 1 restores the one-word discipline for a team that wants it.

The study's items and ratings are in hashira, under eval/results/fragmentation/.

• One dependency. Bundles rubocop-rspec, rubocop-performance, rubocop-elegant, rubocop-packaging, and rubocop-thread_safety behind a single gem. Each runs where it applies: packaging only in a gem, RSpec only where RSpec runs.
• Opinionated defaults. Methods up to 10 lines and bounded by complexity, classes under 100, 4 parameters max, 120-column lines, double quotes, every pending cop kata reviewed. See config/default.yml.
• Safe autocorrect, by structure. rubocop -a runs a correction only when it changes layout (whitespace, line breaks, indentation, comment layout), delimiters or quotes — never the content of a string, heredoc or regexp — or swaps syntax for an exact equivalent that resolves no name or method the project could define, flips no receiver of ==, merges or splits no condition, and moves, duplicates or drops no expression. It renames, anonymises or forwards no parameter either: an x-string, an eval string or binding may read a parameter by name (Opal's backtick JavaScript does), and a method's reflected signature (Method#parameters, YARD's @param) is part of its contract. data/autocorrect.txt files each one under layout, delimiter or equivalent with its reason, and each correction a field test caught breaking code under held, with what it broke; every other correction waits for rubocop -A. So rescue => e is not rewritten to a StandardError the project may define, a guard clause is not hoisted past a fail the class may define, not a < b does not become a >= b, and a local is not inlined.
• -a writes only what keeps the program's text. Before rubocop -a writes a corrected file (or hands --stdin its result), kata parses it with Prism and compares the values of its string-like literals — strings, heredocs, x-strings, regexps and symbols, adjacent literals joined, each interpolation a placeholder whose own literals count on their own, quotes and delimiters ignored — with the original's. A + between two literals is a call, not a join: it builds a new, unfrozen String where adjacent literals were one frozen String (so Layout/RedundantLineBreak, which wrote one, reports the line break between adjacent literals but never joins it). A file the corrections would leave unparsable, or whose literal values they would change, is kept as it was, with one line on stderr naming the corrections it refused: rubocop-kata: kept lib/sql.rb as it was: -a would have changed the literal on line 4 (refused: Layout/TrailingWhitespace). The report and the exit status then describe the file as it was kept: its offenses are reported as not corrected, so rubocop -a && git diff --exit-code fails on it as a plain run would. That catches a layout correction that strays into a literal (RuboCop's Layout/TrailingWhitespace inside a multi-line string, Layout/IndentationWidth inside a multi-line regexp) wherever it comes from. The same check, and the same held corrections, apply to rubocop -x, which kata runs as -a narrowed to layout; only -A writes everything it corrects. It needs RuboCop 1.91 or later, which writes each file once; when a plugin's extra Ruby extractor makes RuboCop write each pass to the file itself, kata checks the file it wrote and writes the original back. The guarantee is Ruby's semantics, not the text other tools read: a gemspec that greps version.rb for single quotes is the reason Style/StringLiterals leaves version files alone.
• Rails out of the box. In a Rails app kata knows the names Rails and its common gems dictate and the files the generators write, and relaxes nothing else.
• Thirty-nine house cops. Naming, dependency discipline, immutability, and data honesty in the Elegant Objects spirit — from Kata/GoodClassName to Kata/FrozenState. Twelve of them run only under the strict Elegant Objects profile, which also turns on a stricter reading of nine others.

class PaymentProcessor  # Kata/GoodClassName: `PaymentProcessor` names a doer; name the class
end                     #   for the thing it is, not the work it does.

class Payment           # OK
end

A doer is an agent noun, not a word that ends in -er: data derived from WordNet says whether a word's dominant sense is "one that parses" (Parser, Timer) or a thing (Number, Layer, Order, Folder). On 400 labelled names its precision is 0.99 where the old "is the stem a word" test scored 0.75 (see eval/results). It suggests a name only when it can derive one (Selector → Selection).

Add the gem to your Gemfile:

gem "rubocop-kata", group: :development, require: false

Install it and point .rubocop.yml at the plugin:

plugins:
  - rubocop-kata

AllCops:
  TargetRubyVersion: 3.4

bundle install
bundle exec rubocop

That's it. The plugin loads the bundled extensions and the shared defaults, so your .rubocop.yml keeps only what's specific to your project. Requires Ruby >= 3.4 and RuboCop ~> 1.75 (1.75.1 or later).

The plugin finds the project's root — the directory of the .rubocop.yml that loads it, or else the nearest directory, from where RuboCop runs upwards, that holds a Gemfile, gems.rb, a *.gemspec or config/application.rb — so rubocop run from app/models, or from one gem of a monorepo, reads the same project as one run from the root. It looks at three things there and shapes the configuration to match:

• A gem (a *.gemspec in the root, or one directory down in a monorepo of gems) gets rubocop-packaging; anything else does not, since its cops are about how a gem is packaged.
• RSpec (a .rspec; rspec, rspec-core or rspec-rails in a Gemfile, lockfile or gemspec at the root or one directory down; or spec files that call RSpec.describe) gets rubocop-rspec; a Minitest suite, even one in spec/, does not.
• Sorbet (sorbet or sorbet-runtime in a Gemfile, lockfile or gemspec, or a # typed: sigil in the first library files) gets config/sorbet.yml: T.let(x, Type), T.cast, T.must, T.unsafe and T.bind read as x, T.nilable(...) and T::Array[...] as types, so a typed constructor or constant table is judged as its untyped twin.
• A Rails app or engine (config/application.rb, or any lib/**/*.rb or <gem>/lib/**/*.rb that subclasses Rails::Engine or calls isolate_namespace) gets config/framework.yml and config/rails.yml on top of the defaults: the method names Rails, Devise, Turbo and Pundit call by name (default_url_options, after_sign_up_path_for, broadcast_target_default, permitted_attributes_for_create), attributes as the role suffix of a nested-attributes writer (time_constraint_attributes= is judged as time_constraint), enum mappings read as lookup tables, and the generated bin/ and db/ files kept out of Kata/NoComments. It relaxes no rule for code the application writes: an association chain, a nil check, a query on a model class or Time.current in a model are still offenses.
• Code built on Rails' frameworks (a Rails app or engine, or a library whose gemspec depends on activerecord, activemodel, activesupport, railties or rails, as friendly_id does) gets config/framework.yml: the names ActiveRecord and ActiveModel send to the project's own classes and records (a namespace's table_name_prefix, a class's model_name and human_attribute_name, relation_delegate_class, a transaction record's rolledback!).

Each choice can be made by hand:

plugins:
  - rubocop-kata:
      rails: false      # or true; also packaging: and rspec:

A .jbuilder template is presentation, so no Kata cop reads it. Vendored and generated code is not the author's: **/vendor/** is excluded wherever it sits, and so are a generator's templates (lib/generators/**/templates/, lib/templates/: files copied into another project, often ERB, which hashira and kimera skip too), and so is a library file with a grammar beside it (parser.rb next to parser.rl, .y, .racc, .treetop or .rex) or a generator's stamp in the comment block it opens with: a line that opens by saying the file was generated ("This file was generated by", "File generated from", "Code generated by", "Generated by", "Auto-generated from", "This is a generated file", "This controller has been generated", after a label such as IMPORTANT:), a line that opens with "do not edit" or "do not modify", a @generated tag, or "DO NOT EDIT" in capitals (stripe-ruby's "File generated from our OpenAPI spec"). Prose that only uses the word (a class comment's "a parameter generated by turning …") is no stamp, and a class's documentation further down ("These are generated by nodes") marks nothing; hashira reads the same stamp. A project's own AllCops: Exclude adds to these paths rather than replacing them (kata's AllCops merges Exclude; write inherit_mode: { override: [Exclude] } under your AllCops to replace the list). A path named on the command line is still inspected. In a monorepo of engines, each engine's <gem>/app/ is read like app/ wherever a default names app/: the files kata inventories (OwnedPaths), the controllers, mailers, helpers and views Kata/FrozenState leaves to Rails, and the Zeitwerk roots Kata/ClassInModule exempts (refinerycms's core/app/controllers/application_controller.rb).

The project's own names are kata's to read, not to re-litigate. Each gem's namespace and the Rails application's module give the project's root constants (the Kata department's Roots: RuboCop::Kata, Roda, Nanoc::Core). A gem's root is the namespace it defines, as its code spells it, through its require path (nanoc-core → nanoc/core → Nanoc::Core) or a file its entry file requires from its own lib/ (refinerycms-core.rb requires refinery/core: Refinery::Core; test-prof → TestProf; http → HTTP), never a camelized gem name the code does not define. The roots are what Kata/GoodModuleName, Kata/GoodClassName and Kata/ClassInModule leave alone, and their snake-case name (in CamelCase words or lowercased, omni_auth_ or omniauth_) counts as a role prefix in Kata/GoodMethodName and Kata/GoodVariableName (pundit_policy_scope, @_pundit_policy_scoped: code mixed into host classes). The dependencies (Gemfile, Gemfile.lock, gemspecs) name technologies: their segments are words for Kata/RealWords (@pagy, sshkit), and a namespace one of them is named for is theirs in Kata/NoTypeCheck however the project reopens it (Kata/NoTypeCheck's Dependencies). The segments of the project's own constant names are words too (zeitwerk's Cref makes cref one). None of these unbans a clipping: args and str stay clippings in a project that names a class Args.

Kata reported four rubocop-elegant defects upstream (#74–#77); 0.8.0 fixes them, but Kata's copies carry further fixes found on real codebases (a heredoc inlined without its body, a lambda's brace, the indent after a nested break), so Kata/NoRedundantVariable, Kata/PairedBrackets, and Kata/ClassInModule stay, and the Elegant/* originals stay off. Elegant/MonotonicIndents stays on, run by kata's own class of that name (lib/rubocop/kata/elegant/monotonic_indents.rb), which skips the lines a multi-line string, regexp or x-string spans, as rubocop-elegant's skips heredoc bodies (the first line too when the literal starts it): their whitespace is the literal's value, not program structure. opal's %x{} holds JavaScript, a backtick holds shell, strong_migrations' messages start at column 0 so their text has no indent, and the line after one is measured from the code before it. rubocop-elegant's configuration also switches off RuboCop cops RuboCop ships on; kata turns Style/ClassVars (global mutable state every subclass shares; another class's setting, Minitest.class_variable_set(:@@installed_at_exit, …), passes) and Lint/NestedMethodDefinition (a def inside a proc or lambda, a body for class_exec, passes) back on, and a spec names the reason each of the others stays off. So do Elegant/NoEmptyLinesInMethods and Elegant/NoEmptyLinesInBlocks, which deleted blank lines inside heredocs and multi-line strings — the text of the program: Kata/NoEmptyLinesInMethods and Kata/NoEmptyLinesInBlocks leave string content alone. They are derived from rubocop-elegant under its MIT licence (see LICENSE.txt). CI tests both the oldest releases the gemspec allows and the newest.

A cop marked strict is off by default and runs under the strict Elegant Objects profile.

kata's defaults judge what most Ruby can meet. The strict profile holds a project to the whole of Elegant Objects: inherit it on top of the plugin.

plugins:
  - rubocop-kata

inherit_gem:
  rubocop-kata: config/strict.yml

It switches on the twelve house cops kata ships off — Kata/FailFast, Kata/ScopedResource, Kata/NoNilArgument, Kata/NoNilReturn, Kata/NoHardWiring, Kata/NoGetter, Kata/FieldCount, Kata/PublicSurface, Kata/NoPublicConstant, Kata/NoReflection, Kata/NoMonkeyPatch and Kata/NoMock — and the stricter reading of nine it ships on: Kata/IoDiscipline's CheckEffects (files, the network, the shell, global streams and services, print), Kata/ClockDiscipline's CheckRandomness, Kata/EnvDiscipline's CheckSettings (the framework's configuration), Kata/NoSingleton's CheckGlobals (CurrentAttributes, thread and request stores, mattr_accessor), Kata/CommandQuery's CheckEveryQuery (every method that answers a value, not only ? methods), Kata/ConstructorDiscipline's CheckPaths (one primary constructor, no allocate), Kata/GoodClassName's CheckContracts (a framework's suffix is a contract only where the class takes part in it), Kata/BuilderNoun's CheckEveryBuilder (build_summary, find_user, load_config) and Kata/NoHashAsObject's CheckTravel (a hash answered or handed on, and a parameter read by its keys). It switches off the sixteen cops a strict one replaces, so nothing is reported twice: Lint/SuppressedException and Style/RescueModifier (Kata/FailFast), Elegant/NoNilReturn (Kata/NoNilReturn), Style/Send (Kata/NoReflection, for a send to another object; a send to self is no longer reported) and the twelve rubocop-rspec cops that report a mock with advice that keeps it (Kata/NoMock): RSpec/VerifiedDoubles (another double), RSpec/MessageSpies and RSpec/InstanceSpy (a spy), RSpec/StubbedMock, RSpec/ReceiveMessages, RSpec/ReturnFromStub, RSpec/ReceiveCounts, RSpec/ReceiveNever and RSpec/VerifiedDoubleReference (the style of a stub), and RSpec/AnyInstance, RSpec/MessageChain and RSpec/SubjectStub (one kind of stub each, every one of which Kata/NoMock reports). Any of them can still be turned back off in the project's own .rubocop.yml. The profile names the plugin itself, so it also works where the project's plugins: sit in another inherited file. Expect a large backlog on most code: the profile flags inelegant code by design.

doctor reports configuration that no longer does anything: an entry in .rubocop.yml or any file it inherits (.rubocop_todo.yml among them) for a cop the configuration disables, a rubocop:disable/enable comment naming a cop that is not enabled where the comment sits, and AllCops: DisabledByDefault: true, under which RuboCop runs only the cops the project's files enable by name, so kata's cops are off until each is enabled by name (Kata/GoodMethodName: with Enabled: true). RuboCop reports none of these. It names any file it could not read or parse, and lists every inline disable with its reason.

bundle exec rubocop-kata doctor          # or: doctor path/to/project

.rubocop.yml:20: `Elegant/GoodMethodName` is disabled by the configuration this project inherits; the entry does nothing.
lib/registry.rb:44: the directive names `Elegant/GoodMethodName`, which is not enabled here; the comment does nothing.
2 dead entries

It exits non-zero when it finds something — a dead entry, or an inline disable without a reason, which Kata/JustifiedDirective reports — so it can gate CI. An entry for a cop RuboCop renamed is named as a rename ("Naming/PredicateName was renamed to Naming/PredicatePrefix; rename the entry"), never as dead: RuboCop applies it to the new name with a warning, or refuses to load the configuration, and doctor then says to rename it in .rubocop.yml.

Kata's structural cops create names and its naming cops charge for them, so a structural refactor removes offenses and adds more. A single total cannot tell progress from regression. plan buckets the backlog into the stages that cause each other and names the one to take next.

bundle exec rubocop-kata plan            # or: plan path/to/project

structure     184  Kata/ConstructorDiscipline 92, Kata/NoHashAsObject 48, Kata/EnvDiscipline 44
naming        263  Kata/RealWords 141, Kata/GoodVariableName 88, Kata/GoodClassName 34
prose          57  Kata/NoComments 57
layout        300  Kata/PairedBrackets 210, Layout/LineLength 90
next: structure — 184 offenses in 61 files; these mint the names `naming` then prices, so take them first
densest: app/models/account.rb (14)

plan always applies kata's defaults beneath the project's own configuration, so on a project that has not named the plugin yet it previews what adopting kata would report, instead of running Kata cops with no configuration at all.

Structure before naming, because doing naming first means renaming things the structural pass is about to move; layout last, because every other stage moves lines.

The gem also ships an agent skill that runs this loop: it works the stage plan names, checks every name it introduces against the same dictionary Kata/RealWords reads, and reports removed and created separately instead of a net total.

mkdir -p .claude/skills/rubocop-kata
bundle exec rubocop-kata skill > .claude/skills/rubocop-kata/SKILL.md

It writes to stdout, so the same command installs it anywhere an agent reads skills from — a project, ~/.claude/skills/, or a plugin.

Double-quoted strings, Metrics/MethodLength: 10 (a wrapped call counts as one line) guarded by Metrics/AbcSize: 17, CyclomaticComplexity: 7 and PerceivedComplexity: 8, two-word names, Metrics/ClassLength: 100, Metrics/ParameterLists: 4, 120-column lines, endless methods on one line, rescue => error (reported, not renamed), and inline disables only with a reason. NewCops stays off: the pending cops kata reviewed are listed one by one, so a RuboCop upgrade adds no autocorrect nobody has read. The core Layout cops stay on, except the five that loop against the no-blank-lines rule and Layout/MultilineOperationIndentation, whose two styles both indent a multi-line if condition by a step Elegant/MonotonicIndents rejects. Lint/SelfAssignment reads Lazy = Lazy inside a class or module as what Ruby makes of it, the outer Lazy named in the nested namespace (a mixin's re-export, in lib/rubocop/kata/outer_constant.rb); at the top level, or qualified, it is still a self-assignment. It reads cookie.expires = cookie.expires as a message to a writer it cannot see (http-cookie's reader computes the expiry, its writer pins it), and reports an attribute copied onto itself only through self with no reader or writer the file defines (lib/rubocop/kata/attribute_copy.rb). Naming/PredicateMethod tells a method that acts and then answers a boolean (ferrum's def clear; @headers = {}; true; end) that a command returns nothing (or self) and raises when it fails, where RuboCop asked for clear?, a query that changes state, which Kata/CommandQuery then rejects (lib/rubocop/kata/success_token.rb). rubocop -a is an allowlist admitted by structure, not by evidence: a suite that stays green proves a correction safe on the code it met, not on the next codebase (data/autocorrect.txt; script/autocorrect writes config/autocorrect.yml from it, and eval/run runs the corpora's suites to find bugs in what the rule admits). So -a deletes no comment, renames no ivar, rescue variable or parameter, swaps no name for one the project may define, moves no expression, keeps RBS and Steep annotations, and writes no file whose string, regexp or symbol values it would change; everything else is -A. See config/default.yml.

The six object-discipline cops (NoSetter, FrozenState, NoOutputArgument, CommandQuery, NoTypeCheck, NoSingleton) and NoClassMethodLogic's module rule shipped with a blind precision check: an independent rater, who saw only the shuffled offenses and the codebases, labelled up to 25 per cop on faraday, rubygems.org, hashira and kimera:

The per-corpus counts and every label are in eval/results.

Whether a cop is on is decided by the philosophy, not by that number. The rater asked whether a reviewer would ask for the change, which carries convention back in ("standard Rails", "idiomatic"). A cop is on when it reads the code correctly and its advice is what Elegant Objects asks for; where an offense was a misread, the cop changes. NoTypeCheck was off because most checks it reported tested a class another library owns, where polymorphism cannot reach; scoped to the project's own types, it reports only the checks polymorphism would remove.

eval/run --kata PATH scores a checkout: labelled cases per cop under the shipped defaults, 400 labelled -er/-or/-ar names, the rubocop-kata commands, and pinned codebases for offenses per kLOC and for what -a and -A leave behind. eval/results holds this release against the previous one.

The code is MIT — see LICENSE.txt. The shipped dictionaries are third-party data under their own terms:

• data/words.txt.gz — a modified subset of SCOWL en-US size 60: filtered, deduplicated, and gzipped. SCOWL is the collective work of Kevin Atkinson and the contributors named in data/SCOWL-COPYRIGHT, which is distributed with this gem and reproduced verbatim. It includes, among others, Copyright 2000–2018 Kevin Atkinson; WordNet 1.6 Copyright 1997 by Princeton University, all rights reserved; and Copyright 1993 Geoff Kuenning, Granada Hills, CA, all rights reserved. Princeton University makes no representations or warranties, express or implied, as to this database, and its name may not be used in advertising or publicity pertaining to this distribution.
• data/software.txt.gz — built from the software-terms, ruby, and shell dictionaries of cspell-dicts, each MIT-licensed. Copyright (c) 2017–2025 Street Side Software; the notice and permission text are reproduced in data/CSPELL-LICENSE.
• data/agents.txt.gz, data/things.txt.gz, data/verbs.txt.gz — derived from WordNet 3.0 by script/wordnet. WordNet 3.0 Copyright 2006 by Princeton University, all rights reserved; its licence is reproduced in data/WORDNET-LICENSE.
• data/supplement.txt, data/clippings.txt and data/actions.txt — this project's own additions, MIT.