kfitzpatrick · Sep 14, 2026 · Sep 14, 2026 · kfitzpatrick · Sep 14, 2026 · devill
diff --git a/docs/smell-vocabulary.md b/docs/smell-vocabulary.md
@@ -35,6 +35,7 @@ exits 0. The mapper config can override it per project.
 | `deep-nesting`              | Deep nesting                          | enforced         |
 | `oversized-file`            | Oversized file                        | enforced         |
 | `oversized-block`           | Oversized block                       | enforced         |
+| `multiple-expectations`     | Multiple expectations                 | enforced         |
 | `unused-variable`           | Unused variable                       | enforced         |
 | `loose-equality`            | Loose equality                        | enforced         |
 | `var-declaration`           | `var` declaration                     | enforced         |
@@ -189,6 +190,7 @@ catalogue is shared, only the plugin's sensors differ).
 | `rubocop:Metrics/ParameterLists`        | `too-many-parameters` |
 | `rubocop:Metrics/MethodLength`          | `oversized-function`  |
 | `rubocop:Metrics/BlockLength`           | `oversized-block`     |
+| `rubocop:RSpec/MultipleExpectations`    | `multiple-expectations` |
 | `rubocop:Metrics/CyclomaticComplexity`  | `high-complexity`     |
 | `rubocop:Metrics/PerceivedComplexity`   | `high-complexity`     |
 | `rubocop:Metrics/AbcSize`               | `high-complexity`     |

diff --git a/plugins/ruby/src/habit_hooks_ruby/guides/multiple-expectations.md b/plugins/ruby/src/habit_hooks_ruby/guides/multiple-expectations.md
@@ -0,0 +1,46 @@
+Keep each example focused on one behavior and one clear reason to fail.
+Split unrelated expectations into separate examples, sharing setup through
+`before`, helpers, or `let` where useful.
+
+Bad — unrelated behavior is bundled into one example:
+
+```ruby
+it "creates and announces the account" do
+  account = create_account
+
+  expect(account).to be_persisted
+  expect(account.plan).to eq("free")
+  expect(Mailer).to have_received(:welcome).with(account)
+end
+```
+
+Good — each behavior has its own example:
+
+```ruby
+subject(:create_account) { described_class.call }
+
+it "persists the account" do
+  expect(create_account).to be_persisted
+end
+
+it "assigns the free plan" do
+  expect(create_account.plan).to eq("free")
+end
+
+it "sends the welcome email" do
+  account = create_account
+
+  expect(Mailer).to have_received(:welcome).with(account)
+end
+```
+
+Multiple expectations can be appropriate when they jointly describe one
+inseparable outcome. Use judgment: improve the test’s focus and diagnostic value;
+do not combine assertions, add `aggregate_failures`, or disable the cop merely to
+silence RuboCop.
+
+Locations reported:
+
+{% for issue in issues -%}
+{{ issue.details.file }}:{{ issue.details.line }} — {{ issue.details.message }}
+{% endfor %}
diff --git a/plugins/ruby/src/habit_hooks_ruby/sensors/rubocop_report.py b/plugins/ruby/src/habit_hooks_ruby/sensors/rubocop_report.py
@@ -38,6 +38,7 @@
     "Metrics/ParameterLists": "too-many-parameters",
     "Metrics/MethodLength": "oversized-function",
     "Metrics/BlockLength": "oversized-block",
+    "RSpec/MultipleExpectations": "multiple-expectations",
     "Metrics/CyclomaticComplexity": "high-complexity",
     "Metrics/PerceivedComplexity": "high-complexity",
     "Metrics/AbcSize": "high-complexity",

diff --git a/plugins/ruby/tests/test_the_rubocop_pipeline_maps_cops_to_smells.py b/plugins/ruby/tests/test_the_rubocop_pipeline_maps_cops_to_smells.py
@@ -67,6 +67,13 @@ def test_every_mapped_cop_reaches_its_smell(cop: str) -> None:
     assert finding["issues"][0]["details"]["source"] == f"rubocop:{cop}"
 
 
+def test_multiple_expectations_reaches_its_guide_smell() -> None:
+    [finding] = findings([_entry("RSpec/MultipleExpectations")])
+
+    assert finding["smell"] == "multiple-expectations"
+    assert finding["issues"][0]["details"]["source"] == "rubocop:RSpec/MultipleExpectations"
+
+
 def test_findings_are_grouped_by_smell_and_sorted() -> None:
     """One finding per smell whatever order the offences arrive in. The output
     is compared byte for byte by the spec cases, so it has to be deterministic."""