rails-hyperdrive-martian-spec 0.3.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 761d710c55b5709f60057b13fc4cdd6a48f720c2abdb05a7112ef9b4da93c805
+  data.tar.gz: 071ff2fe7200c95bdcdb9ea7fc436055e7a2f17e7a587852a34fc3029ee76e00
+SHA512:
+  metadata.gz: 12fd655921158c815a0cd98331e0cb2f9c25b13f9eec9aa7b5b599e78bfa710f4659c6bfd06276762312bb03c6d8a005c1a34e71a143aec83f706f3a0f91da65
+  data.tar.gz: c4b8b868e5d97d25e925006b86171402877a3b4d615869a2991d5b037335b4a3c1f08f158418a3a1aeddea2bff42a73eeff4b6be1ecae397105cc38a581bf1d0

data/CHANGELOG.md

@@ -0,0 +1,92 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.3.1] - 2026-09-01
+
+### Fixed
+- Profiler slash commands are gated on both rspec-rails and test-prof. A
+  per-entry `gem:` in the manifest replaces the gem-wide rspec-rails gate, so
+  the seven profiler commands used to install into bundles that had test-prof
+  but no rspec-rails. 0.3.0 was tagged but never published to rubygems.
+
+## [0.3.0] - 2026-09-01
+
+### Added
+- Slash commands as a second artifact kind, installed into `.claude/commands/`:
+  seven test-prof profilers (`/fprof`, `/event-prof`, `/rd-prof`, `/tps-prof`,
+  `/factory-default-prof`, `/mem-prof`, `/stack-prof`, gated on test-prof via
+  the manifest `commands:` section), two ungated RSpec diagnostics
+  (`/slowest-specs`, `/bisect-order`), and a `/profile-specs` entry point
+  templated for bundles with and without test-prof. Each command carries the
+  flag, result interpretation, and a usage example.
+- `martian-spec` skill: supporting references extracted from the skill body —
+  `data-setup.md` (test-prof decision tables, checklist, `refind:`, red flags,
+  symptom table), `profiling.md` (runnable cheat-sheet commands, pointing at
+  the slash commands), `structure.md` (ordering convention with annotated
+  example) — all three conditional on test-prof — and `parallel-ci.md`
+  (runner comparison, per-worker databases, shared-cache namespacing),
+  installed unconditionally.
+- `martian-spec` skill: `allowed-tools` frontmatter; a "Never hit real
+  external APIs" rule with WebMock/VCR notes gated on those gems; a gated
+  bcrypt cost snippet; generic flaky-spec diagnostics (factory profiling via
+  `ActiveSupport::Notifications`, time-leak and `before(:context)` checks);
+  a named-subject convention; a cache-store-aware failsafe checklist.
+- `martian-spec` skill: when the bundle lacks test-prof, the installed skill
+  instructs the agent to suggest adding it (`bundle add test-prof --group
+  test` plus recipe requires) rather than adding it silently.
+- `Rakefile` wiring rails-hyperdrive's author-side manifest lint
+  (`rake hyperdrive:manifest:check`) and a CI workflow running it.
+  `rails-hyperdrive` and `rake` are development-only Gemfile dependencies.
+
+### Changed
+- Migrated to the rails-hyperdrive 0.8.0 companion contract. The skill is a
+  standalone master template
+  (`lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/SKILL.md.erb`
+  with `references/` alongside it) rendered per-app at install; content varies
+  with the consuming app's bundle via `gem?` blocks (test-prof, graphql,
+  rspec-sidekiq, sidekiq, webmock, vcr, bcrypt). Old `gem:`/`versions:`
+  frontmatter gating moved into a gem-root `hyperdrive.yml`, where the
+  requirement rides on the target member
+  (`gems: [rspec-rails: ">= 6.0, < 9.0"]` — the `versions:` key is retired).
+  Gemspec discovery metadata keys renamed from `rails_hyperdrive_*` to
+  `hyperdrive_targets` / `hyperdrive_artifacts` (now `"skill,command"`), the
+  keys `hyperdrive:discover` reads since rails-hyperdrive 0.6.
+- `martian-spec` skill description rewritten without third-party gem mentions;
+  the intro, layer table, and examples generalized (handler example is a plain
+  request spec; "Worker spec" is "Job spec").
+- `martian-spec` skill: wrong-layer guidance reworded as design-smell signals
+  ("flag it, put coverage where the logic lives") instead of extraction
+  directives; the duplicate wrong-layer escalation ladder was dropped.
+- Renamed the gem from `rails-hyperdrive-rspec` to `rails-hyperdrive-martian-spec`.
+  The `RailsHyperdriveRspec` module is now `RailsHyperdriveMartianSpec` and the
+  entrypoint is `require "rails-hyperdrive-martian-spec"`. `rails-hyperdrive-rspec`
+  0.2.0 remains on rubygems but receives no further releases.
+
+## [0.2.0] - 2026-08-06
+
+### Added
+- Initial scaffold of the companion gem.
+- `martian-spec` skill targeting `rspec-rails`.
+- `martian-spec` skill: "Suite-level speed (CI)" section covering log quieting,
+  weakening cryptographic KDFs in test, fair parallelization, and global
+  failsafes for leaky state.
+- `martian-spec` skill: profiler cheat-sheet mapping each test-prof env flag to
+  its tool and the question it answers.
+- Gemspec discovery metadata (`rails_hyperdrive_targets`,
+  `rails_hyperdrive_artifacts`) so `hyperdrive:discover` finds the gem on
+  rubygems before it is bundled.
+
+### Changed
+- `martian-spec` skill description: also triggers when implementing a new
+  feature or fixing a bug, not only when touching spec files directly.
+
+[Unreleased]: https://github.com/izhanov/rails-hyperdrive-martian-spec/compare/v0.3.1...HEAD
+[0.3.1]: https://github.com/izhanov/rails-hyperdrive-martian-spec/compare/v0.3.0...v0.3.1
+[0.3.0]: https://github.com/izhanov/rails-hyperdrive-martian-spec/releases/tag/v0.3.0
+[0.2.0]: https://github.com/izhanov/rails-hyperdrive-martian-spec/releases/tag/v0.2.0

data/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 izhanov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,19 @@
+# rails-hyperdrive-martian-spec
+
+Companion gem for [rails-hyperdrive](https://github.com/rails-hyperdrive/rails-hyperdrive) — ships the `martian-spec` skill for AI coding agents working with RSpec in Rails projects.
+
+## Install
+
+```ruby
+# Gemfile
+group :development do
+  gem "rails-hyperdrive"
+  gem "rails-hyperdrive-martian-spec"
+end
+```
+
+Then run `bin/rails hyperdrive:init`. The skill is installed to `.claude/skills/martian-spec/SKILL.md` and loaded lazily by Claude Code when relevant.
+
+## License
+
+MIT — see [LICENSE.txt](LICENSE.txt).

data/commands/bisect-order.md

@@ -0,0 +1,21 @@
+---
+description: Isolate the minimal failing example pair for an order-dependent spec
+argument-hint: <seed> [spec file or directory]
+---
+
+Reproduce and minimize an order-dependence with RSpec's bisect (the seed comes
+from the failing CI/local run's output — ask for it if missing):
+
+```sh
+bundle exec rspec --seed $ARGUMENTS --bisect
+```
+
+Interpret: bisect prints the minimal set of examples that must run together to
+reproduce the failure. The *earlier* example in the pair leaks state (time,
+mocks, DB records outside the transaction, Redis/cache); the later one is the
+victim. Check the leak diagnostics in the `martian-spec` skill's Escalation
+Ladder to classify and fix it.
+
+Example: `/bisect-order 54321 spec/models/`
+
+Report the minimal failing pair, the leaked state, and the fix.

data/commands/event-prof.md

@@ -0,0 +1,21 @@
+---
+description: Measure time spent in one event type (test-prof EventProf), e.g. SQL or factories
+argument-hint: <spec file or directory> [event]
+---
+
+Run test-prof's EventProf against the given path (ask for one if missing).
+The second argument is the event; default to `sql.active_record`:
+
+```sh
+EVENT_PROF='sql.active_record' bundle exec rspec <path>   # time in SQL
+EVENT_PROF='factory.create' bundle exec rspec <path>      # time in factories
+```
+
+Interpret the share, not the absolute number: if SQL is ~10% of total time,
+don't chase N+1s — profile factories and hooks instead. If factories dominate,
+follow up with `/fprof` to find which ones.
+
+Examples: `/event-prof spec/models/user_spec.rb`,
+`/event-prof spec/services/ factory.create`
+
+Report the event's share of total time and where to look next.

data/commands/factory-default-prof.md

@@ -0,0 +1,22 @@
+---
+description: Find implicit associations that create_default could share (test-prof FactoryDefault)
+argument-hint: <spec file or directory>
+---
+
+Run test-prof's FactoryDefault profiler against the given path (ask for one if
+missing):
+
+```sh
+FACTORY_DEFAULT_PROF=1 bundle exec rspec $ARGUMENTS
+```
+
+Interpret: the report counts how often each factory was created as an implicit
+association — high counts are records `create_default` could share instead of
+re-creating. Caveat: `create_default` only intercepts top-level factory
+associations, not associations defined inside traits — for trait cascades,
+eliminate the trait instead (see the `martian-spec` skill's
+`references/data-setup.md`).
+
+Example: `/factory-default-prof spec/models/`
+
+Report the top shareable associations and whether `create_default` applies.

data/commands/fprof.md

@@ -0,0 +1,21 @@
+---
+description: Count factory runs per factory (test-prof FactoryProf) to find cascades
+argument-hint: <spec file or directory>
+---
+
+Run test-prof's FactoryProf against the given path (ask for one if missing —
+whole-suite runs drown the signal):
+
+```sh
+FPROF=1 bundle exec rspec $ARGUMENTS
+```
+
+Interpret the table: `top-level` is factories the specs called explicitly,
+`total` includes records spawned through associations and traits. `total` ≫
+`top-level` for a factory means a cascade — trace the gap to an association or
+trait and inline or share it (see the `martian-spec` skill's
+`references/data-setup.md`).
+
+Example: `/fprof spec/services/billing/`
+
+Report the top offending factories, the cascade source for each, and the fix.

data/commands/mem-prof.md

@@ -0,0 +1,20 @@
+---
+description: Find examples contributing most to GC time (test-prof memory profiler)
+argument-hint: <spec file or directory>
+---
+
+Run test-prof's memory profiler against the given path (ask for one if
+missing):
+
+```sh
+TEST_MEM_PROF=gc bundle exec rspec $ARGUMENTS
+```
+
+Interpret: examples at the top allocate the most and drive GC pauses — usual
+suspects are giant fixtures/payloads built per example, `create_list` with big
+counts, and loading large files in setup. Share or shrink the allocation
+rather than tuning GC.
+
+Example: `/mem-prof spec/services/import/`
+
+Report the top allocating examples and what they allocate.

data/commands/profile-specs.md.erb

@@ -0,0 +1,65 @@
+---
+description: Profile RSpec files to find where the time goes (factories, SQL, setup)
+argument-hint: <spec file or directory>
+---
+
+Profile the specs at `$ARGUMENTS` and report where the time goes. If no path
+was given, ask for one — profiling the whole suite drowns the signal in noise.
+
+Usage examples:
+
+```
+/profile-specs spec/models/user_spec.rb
+/profile-specs spec/services/
+```
+
+Run the steps in order and interpret each result before moving to the next.
+<%- if gem?("test-prof") -%>
+
+1. **Find the slowest examples**: `bundle exec rspec --profile 10 $ARGUMENTS`.
+   If the top entries share one feature (e.g. all touch password hashing),
+   suspect expensive global setup, not factories.
+2. **Count factory runs**: `FPROF=1 bundle exec rspec $ARGUMENTS`.
+   `total` ≫ `top-level` for a factory means a cascade — associations or
+   traits creating records the specs never asked for.
+3. **Measure SQL share**: `EVENT_PROF='sql.active_record' bundle exec rspec $ARGUMENTS`.
+   If SQL is a small fraction of total time, don't chase N+1s — look at
+   factories and hooks instead.
+4. **Split hook time from example time**: `RD_PROF=1 bundle exec rspec $ARGUMENTS`.
+   Heavy `before`-hook time with light example bodies points at setup that
+   should be shared (`let_it_be` / `before_all`).
+
+The full flag-by-flag cheat-sheet (including `TPS_PROF`, `TEST_MEM_PROF`,
+`TEST_STACK_PROF`) lives in the `martian-spec` skill's
+`references/profiling.md`.
+<%- end -%>
+<%- if !gem?("test-prof") -%>
+
+1. **Find the slowest examples**: `bundle exec rspec --profile 10 $ARGUMENTS`.
+   If the top entries share one feature (e.g. all touch password hashing),
+   suspect expensive global setup, not factories.
+2. **Count factory runs** with a temporary `ActiveSupport::Notifications`
+   subscriber in `spec/rails_helper.rb` (remove it after diagnosing):
+
+   ```ruby
+   counts = Hash.new(0)
+   ActiveSupport::Notifications.subscribe("factory_bot.run_factory") do |_, _, _, _, payload|
+     counts[[payload[:name], payload[:strategy]]] += 1
+   end
+   at_exit { counts.sort_by { |_, n| -n }.first(20).each { |k, n| puts "#{n}\t#{k.join(" ")}" } }
+   ```
+
+   A factory with a high count that the file never calls explicitly is a
+   cascade — associations or traits creating records the specs never asked for.
+
+This project does not use test-prof, which packages these diagnostics as
+one-env-var profilers (`FPROF=1`, `EVENT_PROF=...`) and adds `let_it_be` /
+`before_all` to fix what they find. Suggest adding it — don't add it silently:
+
+```sh
+bundle add test-prof --group test
+```
+<%- end -%>
+
+Finish with a short report: the top time sinks, whether the bottleneck is
+factories, SQL, hooks, or example bodies, and the single highest-leverage fix.

data/commands/rd-prof.md

@@ -0,0 +1,20 @@
+---
+description: Split before-hook time from example-body time (test-prof RSpecDissect)
+argument-hint: <spec file or directory>
+---
+
+Run test-prof's RSpecDissect against the given path (ask for one if missing):
+
+```sh
+RD_PROF=1 bundle exec rspec $ARGUMENTS
+```
+
+Interpret: heavy `before`-hook time with light example bodies means the setup
+should be shared — `let_it_be` for data, `before_all` for setup (check the
+pre-conversion checklist in the `martian-spec` skill's
+`references/data-setup.md` first). Heavy example bodies point at the code
+under test or over-asserting examples, not setup.
+
+Example: `/rd-prof spec/requests/`
+
+Report the hook/body split for the slowest groups and the conversion candidates.

data/commands/slowest-specs.md

@@ -0,0 +1,20 @@
+---
+description: Print the slowest examples and groups in a spec run
+argument-hint: <spec file or directory>
+---
+
+Run RSpec's built-in profiler against the given path (or the whole suite —
+this one is cheap enough):
+
+```sh
+bundle exec rspec --profile 10 $ARGUMENTS
+```
+
+Interpret: this says *which* examples are slow, not *why*. If the top entries
+cluster around one feature (e.g. everything touches password hashing), suspect
+expensive global setup. Follow up with the profiling steps in the
+`martian-spec` skill's Escalation Ladder to find the cause.
+
+Example: `/slowest-specs spec/`
+
+Report the slowest examples and the pattern they share, if any.

data/commands/stack-prof.md

@@ -0,0 +1,26 @@
+---
+description: CPU flamegraph of the hottest code paths in a spec run (test-prof + stackprof)
+argument-hint: <spec file or directory>
+---
+
+Run test-prof's StackProf integration against the given path (ask for one if
+missing; requires the `stackprof` gem):
+
+```sh
+TEST_STACK_PROF=1 bundle exec rspec $ARGUMENTS
+```
+
+Then inspect the generated dump (path is printed at the end of the run):
+
+```sh
+bundle exec stackprof tmp/test_prof/stack-prof-report-*.dump --text | head -30
+```
+
+Interpret: this answers *what code* burns CPU when factories and SQL are
+already ruled out — crypto/KDF calls (bcrypt, Argon2) in auth-heavy specs are
+the classic finding; weaken their cost in test config, don't optimize specs
+around them.
+
+Example: `/stack-prof spec/requests/auth/`
+
+Report the hottest frames and whether the fix is config, code, or specs.

data/commands/tps-prof.md

@@ -0,0 +1,20 @@
+---
+description: Find files with the most shared-setup overhead per example (best let_it_be candidates)
+argument-hint: <spec directory>
+---
+
+Run test-prof's TPS profiler against the given directory (ask for one if
+missing):
+
+```sh
+TPS_PROF=1 bundle exec rspec $ARGUMENTS
+```
+
+Interpret: files at the top pay the most repeated setup per example — they are
+the best `let_it_be`/`before_all` conversion candidates, where one conversion
+saves the most total time. Verify each against the pre-conversion checklist in
+the `martian-spec` skill's `references/data-setup.md` before converting.
+
+Example: `/tps-prof spec/services/`
+
+Report the top files and the estimated win for converting each.

data/hyperdrive.yml

@@ -0,0 +1,18 @@
+gems:
+  - rspec-rails: ">= 6.0, < 9.0"
+skills:
+  martian-spec:
+    conditional:
+      references/data-setup.md: { gem: test-prof }
+      references/profiling.md: { gem: test-prof }
+      references/structure.md: { gem: test-prof }
+commands:
+  # Per-entry gem: REPLACES the gem-wide rspec-rails gate, so the profiler
+  # commands must re-state it: they need both RSpec and test-prof.
+  fprof.md: { gem: { all: [rspec-rails, test-prof] } }
+  event-prof.md: { gem: { all: [rspec-rails, test-prof] } }
+  rd-prof.md: { gem: { all: [rspec-rails, test-prof] } }
+  tps-prof.md: { gem: { all: [rspec-rails, test-prof] } }
+  factory-default-prof.md: { gem: { all: [rspec-rails, test-prof] } }
+  mem-prof.md: { gem: { all: [rspec-rails, test-prof] } }
+  stack-prof.md: { gem: { all: [rspec-rails, test-prof] } }

data/lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/SKILL.md.erb

@@ -0,0 +1,326 @@
+---
+name: martian-spec
+description: Write, review, optimize, and debug RSpec specs in Rails projects. Use when implementing a feature or fixing a bug in a Rails app — the specs that come with it are part of the change; when creating new spec files or adjusting existing ones; when reviewing test code, PRs, or diffs for anti-patterns and wrong-layer tests; when optimizing slow tests or CI queue time; and when debugging flaky or order-dependent specs. Triggers on "flaky spec", "slow specs", "spec layer", "service/model/request spec", "handler spec", "spec review", "test setup", "test performance", "parallel CI", "test database setup", "RSpec best practices".
+allowed-tools:
+  - Grep
+  - Glob
+  - Read
+  - Edit
+  - Write
+  - Bash
+  - Task
+---
+
+# RSpec for Rails
+
+A skill for writing fast, well-layered, non-flaky RSpec specs in Rails projects.
+
+## Thinking Prompts
+
+Before writing a test context, ask yourself:
+
+- "Could I test this with a simpler object at a lower layer?" -- if yes, do that instead
+- "Am I creating records just to satisfy the entry point, not the logic?" -- wrong layer
+- "Would this test break if I changed the HTTP/GraphQL wrapper?" -- logic is too high
+- "Am I stubbing >3 collaborators just to isolate what I'm testing?" -- testing wiring, not behavior
+- "Is this setup expensive because the logic lives far from where I'm testing it?" -- push logic down
+
+When reviewing existing specs, scan for performance and layer issues:
+
+- "How many records are created per example vs per file?" -- the #1 speed lever
+<%- if gem?("test-prof") -%>
+- "Is there a `before` that could be `before_all`?" -- quick wins first
+<%- end -%>
+- "Are any traits used only for their attributes, not their associations?" -- trait cascades are the #1 hidden waste source
+- "Are any contexts testing a layer above where the logic lives?" -- structural issue, see Red Flags
+
+Then annotate contexts with `[ok]`/`[warning]`/`[error]`:
+
+- `[ok]` -- belongs in this layer
+- `[warning]` -- borderline, signals a design smell
+- `[error]` -- wrong layer, should be tested elsewhere
+
+If a handler (controller action, GraphQL resolver, job `perform`) has > 3 conditional branches (simple guards don't count), that logic is hard to cover at the handler layer -- flag it as a design smell. Don't compensate with a fat handler spec: keep one smoke test at the handler and put full coverage where the logic ends up living.
+
+Before writing a spec with > 5 contexts, sketch the describe/context tree and annotate each with `[ok]`/`[warning]`/`[error]`. If > 30% are `[warning]` or `[error]`, the code needs refactoring before it needs more tests.
+
+### Layer Selection
+
+| What you're testing | Spec layer | Subject pattern |
+|---------------------|------------|-----------------|
+| Business rule / computation | Service spec | `described_class.call(...)` |
+| DB scope / validation / callback | Model spec | `model.method` or `Model.scope` |
+<%- if gem?("graphql") -%>
+| GraphQL field (thin delegation) | Type spec | `MySchema.execute(query, ...)` |
+| GraphQL field with >3 branches | Service spec + type smoke test | Extract first |
+<%- end -%>
+| Background job execution | Job spec | `described_class.new.perform(...)` |
+| Job gets enqueued by caller | Caller's spec | <% if gem?("rspec-sidekiq") %>`have_enqueued_sidekiq_job` / <% end %>`have_enqueued_job` |
+| HTTP endpoint (REST API) | Request spec | `post "/api/path", params:, as: :json` |
+
+### When logic is already at the wrong layer
+
+| Situation | Action |
+|-----------|--------|
+| Writing spec for a handler with > 3 branches | Flag the design smell; one smoke test at the handler, full coverage where the logic ends up living |
+| Reviewing spec with `[error]`-layer contexts | Flag it, don't add more wrong-layer tests |
+| Adding a feature to code that already has wrong-layer tests | Don't compound it — cover what you're touching at the right layer |
+| Can't restructure now (time-pressured) | Minimal handler spec + `# TODO` marking where the logic belongs; when next touching this code, move coverage first |
+
+## Data Setup
+
+- Create the minimum data that exercises the logic: persist only what the code under test actually reads; keep objects in memory when the DB is never touched.
+- Split setup by volatility: data shared by all examples goes in the outermost scope where it's still correct, per-context variations in `let` overrides, mutable state and mocks in `before`.
+- Declare setup in declaration blocks at the top of the `describe`/`context` — never create records inside examples (see Red Flags).
+- Think in totals: every record in shared setup is paid once per example, so a file with 40 examples pays 40× for each one. Trimming shared setup is the highest-leverage speed fix.
+<%- if gem?("test-prof") -%>
+
+With test-prof, static data can be created once per *file* instead of once per
+example — `let_it_be` for records, `before_all` for setup; the single biggest
+speed win. The decision tables, pre-conversion checklist, `refind:` modifiers,
+optimization strategies, red flags, and the broken-conversion symptom table
+live in [references/data-setup.md](references/data-setup.md).
+<%- end -%>
+<%- if !gem?("test-prof") -%>
+
+This project does not use [test-prof](https://test-prof.evilmartians.io). When
+optimizing slow specs, suggest adding it to the user: `let_it_be`/`before_all`
+create shared data once per file instead of once per example (often the single
+biggest suite speedup), and its profilers (`FPROF`, `EVENT_PROF`) pinpoint
+factory and SQL hotspots. Propose the dependency — don't add it silently. If
+the user agrees:
+
+```sh
+bundle add test-prof --group test
+```
+
+then enable the recipes in `spec/rails_helper.rb`:
+
+```ruby
+require "test_prof/recipes/rspec/let_it_be"
+require "test_prof/recipes/rspec/before_all"
+```
+<%- end -%>
+
+## Spec Ordering Convention
+
+Within each `describe`/`context` block, declarations go from stable to
+volatile: `subject`, then data declarations (`let`/`let!`), then setup hooks
+(`before`), then examples, then nested contexts. Data before hooks, hooks
+before examples — a reader should learn *what exists* before *what happens*.
+
+Name the subject (`subject(:result) { ... }`) whenever examples reference it;
+bare `subject` is fine only for `is_expected` one-liners.
+<%- if gem?("test-prof") -%>
+
+With test-prof the same principle splits each tier by lifetime: `let_it_be`
+(static data) before `let`/`let!` (per-context overrides), `before_all`
+(static setup) before `before` (mocks, mutable state). The full convention
+with an annotated example lives in
+[references/structure.md](references/structure.md).
+<%- end -%>
+
+## Critical Rules
+
+### Scope expensive operations narrowly
+Materialized view refreshes, search index reindexing, external data syncs, file generation — scope these to only the contexts that need them. Don't pay the cost for every example.
+
+### Don't over-create records
+To test a `MAX_LIMIT` cap, create `MAX_LIMIT + 1` records, not 600. Extract math into a testable unit and test with plain numbers when possible.
+
+### Make retry delays configurable
+If the service under test has retry logic with `sleep`, make the delay configurable and pass `retry_delay: 0` (or `0.01`) in specs. Never let specs sleep for real.
+
+### Never hit real external APIs
+Specs must not depend on the network: real calls are slow, flaky, and rate-limited. Stub at a boundary you own — wrap third-party calls in a client/adapter class and mock it like any collaborator (`allow(ExternalApi::Client).to receive(:call)`).
+<%- if gem?("webmock") -%>
+
+With WebMock, stub at the HTTP boundary instead: `stub_request(:post, %r{api\.example\.com}).to_return(status: 200, body: ...)`. Disable stray connections globally — `WebMock.disable_net_connect!(allow_localhost: true)` in spec setup — so an unstubbed call fails loudly. Re-enabling net connect inside individual specs is a red flag.
+<%- end -%>
+<%- if gem?("vcr") -%>
+
+With VCR, record real interactions once into cassettes (`record: :once`) and replay them deterministically. Watch for stale cassettes drifting from the live API, and filter secrets before committing (`filter_sensitive_data`).
+<%- end -%>
+
+### One canonical spec per shared resolver / action
+When two endpoints share a resolver or controller action (e.g., a public and an admin endpoint both expose the same `#summary`), test the logic fully in one spec. The other gets a single smoke test with a comment pointing to the canonical spec.
+
+### Handler specs: mock services, don't retest logic
+
+```ruby
+# WRONG -- 9 contexts testing eligibility logic through full HTTP execution
+describe "POST /api/resources/:id/actions" do
+  context "when already performed" do ... end   # business logic
+  context "when owner" do ... end                # business logic
+  # 7 more contexts...
+end
+
+# RIGHT -- handler spec delegates, service spec has full coverage
+describe "POST /api/resources/:id/actions" do
+  subject(:perform_request) { post "/api/resources/#{resource.id}/actions", as: :json }
+
+  let(:service_result) { { allowed: true } }
+
+  before { allow(EligibilityService).to receive(:call).and_return(service_result) }
+
+  it "delegates to the service" do
+    perform_request
+    expect(EligibilityService).to have_received(:call).with(
+      user: current_user, resource: resource
+    )
+  end
+
+  it "returns the service result" do
+    perform_request
+    expect(response.parsed_body).to eq("allowed" => true)
+  end
+end
+```
+
+NEVER add more contexts to a handler spec for delegated logic — if you need to test different service inputs/outputs, those tests belong in the service spec.
+
+## Red Flags
+
+### Layer & coverage
+
+| Pattern | Why | Fix |
+|---------|-----|-----|
+| Business logic tested through GraphQL/HTTP | Slow, brittle, duplicates service coverage | Mock service in handler spec, test logic in service spec |
+| >3 `create` calls to set up a single handler spec context | Handler has business logic that belongs in a service | Flag the smell; cover the logic in a service spec, mock it in the handler spec |
+| Inline job execution in a service spec (`perform_enqueued_jobs`<% if gem?("sidekiq") %>, `sidekiq: :inline`<% end %>) | Exercises 4+ layers in one test, blocks CI queue | Test each layer independently |
+| Testing privates via `send` | Signals class should be decomposed | Extract to smaller public objects |
+| Shared example generating >5 contexts | Test concern at a lower layer instead | Extract and test independently |
+| `skip_callbacks` or `update_columns` in test setup | Fighting the framework to work around side effects | Extract logic to a service/model that doesn't trigger callbacks |
+
+### Factory & mock hygiene
+
+| Pattern | Why | Fix |
+|---------|-----|-----|
+| `create_list` with count >50 | Over-population for boundary test | Use threshold + 1, or test math separately |
+| `FactoryBot.create` inside `subject` or `it` block | Hides setup from the declaration block | Move to `let` / `before` declarations |
+| Factory implicitly creating association trees (cascade) | Every `create` spawns redundant records the test doesn't need | Inline associations in factory definitions or pass shared records explicitly |
+| Trait used only for its attribute defaults, not its associations | Trait associations cascade silently — often the #1 factory waste source | Replace trait with explicit attributes; check model scopes to know which attributes are required |
+| Optional associations defined in factory default | Every `create` pays for associations the test doesn't need | Remove from factory; add explicitly in tests that need them |
+| `allow_any_instance_of(Klass)` | Fragile, unclear which instance is stubbed | Inject dependency or stub on the specific object |
+| Mocking internal code | Over-mocking hides real bugs; only external APIs need isolation | Stub at the external boundary (see Never hit real external APIs); let internal code run |
+
+### General
+
+| Pattern | Why | Fix |
+|---------|-----|-----|
+| Spec file >1,000 lines | Skews CI queue — one worker stuck while others idle | Split by domain |
+| `sleep` in specs | Wastes real wall-clock time; usually masks retry backoff or async waiting | Retry: make the delay configurable, pass 0 (see Critical Rules). Async: poll for the condition, don't wait a fixed time |
+| `before` block with >5 stubs | Service has too many responsibilities | Decompose service |
+| `rubocop:disable Rails/Output` | Specs must be automated, not human-verified | Remove debug output |
+
+## Escalation Ladder: flaky or slow spec
+
+Diagnostics, roughly in this order:
+
+- **Reproduce ordering issues**: `bundle exec rspec --seed <seed> --bisect` to isolate the minimal failing pair.
+- **Profile factory usage**: factory_bot instruments every factory run — tally the counts with a plain `ActiveSupport::Notifications` subscriber. A factory with a high count that the file never calls explicitly is a cascade from associations or traits.
+
+  ```ruby
+  # ad hoc in rails_helper.rb while diagnosing
+  counts = Hash.new(0)
+  ActiveSupport::Notifications.subscribe("factory_bot.run_factory") do |_, _, _, _, payload|
+    counts[[payload[:name], payload[:strategy]]] += 1
+  end
+  at_exit { counts.sort_by { |_, n| -n }.first(20).each { |k, n| puts "#{n}\t#{k.join(" ")}" } }
+  ```
+<%- if gem?("test-prof") -%>
+  - **With test-prof profiling is one env var**: `FPROF=1 bundle exec rspec spec/path/to/file.rb` shows top-level vs total factory counts (a large gap = cascade); `EVENT_PROF='sql.active_record' bundle exec rspec` surfaces SQL hotspots.
+  Cheat-sheet in [references/profiling.md](references/profiling.md).
+<%- end -%>
+- **Find slow examples**: `--profile 10` prints the slowest 10.
+- **State-leak suspect?** Check for Redis/cache writes, `update_columns`, or model callbacks that bypass the transaction.
+- **Time-leak suspect?** `travel_to` / `freeze_time` without a matching `travel_back` (use the block form, or an `after` hook) leaks frozen time into later examples.
+- **Leaking `before(:context)`?** Records created there bypass the per-example transaction, and RSpec forbids mocks in it — move both to `before`.
+<%- if gem?("test-prof") -%>
+- **Using `before_all` / `let_it_be`?** The same time/mock/state leaks have test-prof-specific symptoms — see the symptom table in [references/data-setup.md](references/data-setup.md).
+<%- end -%>
+
+## Suite-level speed (CI)
+
+Everything above tunes individual examples. These levers work on the whole
+suite at once — three cut CI time and one guards the parallel setup. Do them
+roughly in this order — the first is almost free and often the biggest.
+<%- if gem?("test-prof") -%>
+
+Even a suite fully converted to `let_it_be`/`before_all` still pays these
+costs — suite-level levers are the next step after data-setup tuning, not a
+replacement for it.
+<%- end -%>
+
+### 1. Quiet the logs (do this first)
+
+The default test `log_level` is `:debug`, so every SQL statement is written to
+`log/test.log` — a suite emitting tens of thousands of queries pays real I/O for
+output nobody reads. In `config/environments/test.rb`:
+
+```ruby
+config.log_level = :fatal
+config.active_record.verbose_query_logs = false     # no per-query backtrace
+config.active_record.query_log_tags_enabled = false  # no SQL comment tagging
+```
+
+Usually the biggest cheap win in a suite that has never been tuned: in Evil
+Martians' write-up, quieting the verbose query logs together with a Sentry
+logger fix took a single-process run from ~25min to ~12min, with the query
+logging doing the heavy lifting. Costs nothing and never changes behavior.
+
+### 2. Weaken expensive global setup in test
+
+Cryptographic KDFs (Argon2id, bcrypt, scrypt, PBKDF2), blind indexes, and
+password hashing are CPU bottlenecks that dominate the *slowest examples* —
+they're designed to be slow. Use minimal cost in test only: expose the cost
+parameters (`t_cost`/`m_cost`/`p_cost`, iteration counts) as env-aware config
+and use the cheapest values in the test environment.
+<%- if gem?("bcrypt") -%>
+
+```ruby
+BCrypt::Engine.cost = BCrypt::Engine::MIN_COST   # in test setup
+```
+<%- end -%>
+
+Find them: they're the top entries in `--profile`. If your slowest specs are all
+one crypto/auth feature, this is the fix, not factory work.
+
+### 3. Parallelize fairly (runner choice matters)
+
+Running across CPU cores is the biggest wall-clock lever once the above are
+done, but the runner matters: prefer a *fair queue* (`test-queue` — one boot,
+examples handed to free workers) over static file splitting
+(`parallel_tests` — the slowest file strands a worker), and give each worker
+its own database. The runner comparison, per-runner database setup (including
+the `test-queue` custom-runner snippet), CI core counts, and how to tell an
+isolation bug from a runner problem live in
+[references/parallel-ci.md](references/parallel-ci.md).
+
+### 4. Global failsafes for leaky state
+
+Leaked global state (frozen time, singletons, cache entries) causes flakes
+even in a single process; a parallel runner just widens the blast radius to
+unrelated specs in other workers. Add belt-and-suspenders resets in
+`spec/rails_helper.rb`:
+
+```ruby
+config.after { travel_back }  # undo any stray travel_to/freeze_time
+# reset any singletons / global clients / thread-locals the app sets
+```
+
+For the cache, check what `config/environments/test.rb` actually sets before
+adding a failsafe:
+
+- **`:null_store`** (the Rails default in test) — cache writes are no-ops,
+  nothing to clear. But if the app talks to Redis *directly* (job queues,
+  custom clients, counters), those writes survive the DB transaction — clear
+  or namespace them in an `after` hook instead.
+- **`:memory_store`** — per-process; `config.after { Rails.cache.clear }` is
+  cheap and sufficient.
+- **A shared store** (`:redis_cache_store`, memcached) — one worker's `clear`
+  wipes every other worker's entries: namespace the store per worker first,
+  then clear — setup in [references/parallel-ci.md](references/parallel-ci.md).
+
+Prefer fixing the leak at its source (the time-leak / mock-leak red flags
+above); the global `after` is the safety net for what slips through.

data/lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/data-setup.md

@@ -0,0 +1,176 @@
+# Data Setup (test-prof)
+
+`let_it_be` and `before_all` create data once per spec file instead of once
+per example — the single biggest per-example speed win. This reference holds
+the decision rules, the safety red flags, and the recovery ladder.
+
+## Critical Rules
+
+### `let_it_be` by default
+Use `let_it_be` for all static data (see Quick Reference above). This is the single biggest speed win — heavy specs often drop from hundreds of factory creates to a handful.
+
+### `before_all` for static setup
+If a `before` block only creates records or sets up static state (no mocks), use `before_all`.
+
+## Quick Reference
+
+### Use `let_it_be` when:
+
+| Situation | Variant | Why |
+|-----------|---------|-----|
+| Data never changes between examples | `let_it_be(:x) { create(...) }` | Created once, shared across examples |
+| Record mutated by code under test | `let_it_be(:x, refind: true)` | `refind: true` does a full `find` after each example (fresh Ruby object); use `let` if mutation is destructive (soft-delete, discard) |
+| Static setup (no mocks involved) | `before_all { create(...) }` | Runs once, not per example |
+
+### Keep as `let` when (NOT `let_it_be`):
+
+| Situation | Why |
+|-----------|-----|
+| Value overridden in nested contexts | `let_it_be` is frozen at creation; nested `let` overrides won't affect it |
+| ANY dependency in the chain is overridden in nested contexts | Transitive: if the root is overridden, every dependent that references it must ALL stay as `let` — `let_it_be` records were created with the original dependency |
+| Nested context creates records with unique constraints on a shared object | `let_it_be` reuses the same DB record; a nested `create` hitting a unique index raises `RecordNotUnique` |
+| Factory or setup writes to Redis/cache | Transaction savepoints only roll back DB state; cache/Redis writes persist across examples |
+| References another `let` that varies | Depends on per-context data that `let_it_be` can't see |
+| Setup involves mocks, stubs, or test doubles (`double`, `instance_double`, `spy`) | Mocks and doubles are scoped to one example; `let_it_be` leaks them into subsequent examples causing "leaked into another example" errors |
+| Time-sensitive logic | `before_all` / `let_it_be` freezes time across all examples and leaks to other files; use `before { travel_to(time) }` |
+| `before` block creates records referencing data that sibling contexts override | `before_all` records persist across ALL sibling contexts; if a sibling redefines a dependency, the `before_all` records still reference the original — keep as `before` |
+
+### Pre-conversion checklist: `let` → `let_it_be`
+
+Before converting, verify ALL of these:
+- [ ] No nested `let` override of any dependency in the chain
+- [ ] No unique constraints on the shared object in nested contexts
+- [ ] No Redis/cache writes in the factory or setup
+- [ ] Declaration appears AFTER all its `let_it_be` dependencies in source order
+- [ ] No model callbacks (`before_commit`, `after_commit`) on created records that implicitly create other persistent records (these survive savepoint rollback and cause unique constraint violations)
+- [ ] For `before` → `before_all`: no sibling context overrides any data the block references (records leak across siblings)
+
+**`let_it_be` modifiers:** Prefer `refind: true` over `reload: true` — `reload: true` is a half-measure that re-reads attributes but keeps the same Ruby object, while `refind: true` does a full `Model.find` returning a completely fresh object. When neither modifier works (soft-delete, `discard`), fall back to `let`.
+
+**`refind: true` side-effect:** `refind` issues a `SELECT *` per example. If the spec asserts on SQL events, filter out the reload query.
+
+### Optimization strategies (don't leave speed on the table)
+
+**Use `refind: true` to unlock cascading conversions.** When a record is mutated in nested contexts (e.g., `user.save!`, `record.update!`) but NOT destroyed, use `let_it_be(:record, refind: true)` instead of falling back to `let`. This lets all dependents also become `let_it_be`, saving dozens of factory calls. Only fall back to `let` when the mutation is destructive (soft-delete, discard).
+
+**Use `refind: true` when sibling contexts load the same association.** Without `refind`, `let_it_be` reuses the same Ruby object across all contexts. If context A's `before` creates child records and the example loads the association (e.g., `user.posts`), the association cache persists on the Ruby object even after the records are rolled back. Context B then gets stale cached data instead of querying the DB. `refind: true` returns a fresh Ruby object per example, with no stale association cache.
+
+```ruby
+# BEFORE: user mutated in contexts → entire chain stays `let`
+let(:user) { create(:user) }
+let!(:post) { create(:post, user: user) }
+let!(:comment) { create(:comment, post: post) }
+let!(:reaction) { create(:reaction, user: user) }
+
+# AFTER: refind on the root unlocks the whole chain
+let_it_be(:user, refind: true) { create(:user) }
+let_it_be(:post) { create(:post, user: user) }
+let_it_be(:comment) { create(:comment, post: post) }
+let_it_be(:reaction) { create(:reaction, user: user) }
+```
+
+**Convert nested single-context declarations.** A `let` inside a context with 1-2 examples and no nested overrides is safe to convert to `let_it_be`. Don't skip these — a file with 20 contexts × 2 examples = 40 unnecessary factory calls if you only optimize the top level. Scan every `describe`/`context` block.
+
+**Hoist duplicate `let` declarations.** When multiple sibling contexts define identical `let(:x) { create(...) }`, hoist the declaration to the shared parent scope. If the parent uses `let_it_be`, the hoisted declaration can too — one factory call instead of N.
+
+**Convert pure-Ruby declarations.** `let` blocks that build non-DB objects (anonymous classes, schema definitions, static hashes) are always safe to convert to `let_it_be` — no DB rollback concerns.
+
+**Break factory cascades by passing shared objects.** When a factory implicitly creates associations, each `create` spawns redundant records. Pass existing `let_it_be` objects to short-circuit the cascade.
+
+```ruby
+# BEFORE: 3 contexts × create(:post) = 3 users + 3 categories created implicitly
+let(:post) { create(:post) }
+
+# AFTER: share the parent objects, pass them explicitly
+let_it_be(:user) { create(:user) }
+let_it_be(:category) { create(:category) }
+let_it_be(:post) { create(:post, user: user, category: category) }
+```
+
+**Eliminate expensive traits that the spec doesn't need.** Factory traits with associations are hidden cascade sources — each trait association spawns its own dependency tree. Profile factories (e.g., test-prof's `FPROF=1`) and look for factories where `total` >> `top-level`; trace the gap to a trait, then replace the trait with only the explicit attributes the test actually requires.
+
+```ruby
+# BEFORE: :with_full_profile creates address + avatar + preferences,
+# each cascading to additional records
+create(:user, :with_full_profile)
+
+# AFTER: replace trait with the attributes the code under test actually checks
+create(:user, status: "active", role: "admin")
+```
+
+**Check model scopes when replacing traits.** When you remove a trait, verify which attributes the code under test actually requires. If the service calls `User.visible` and that scope requires `status: "active"`, you must set `status` explicitly — the trait was setting it silently. Read the scope definition before choosing replacement attributes.
+
+**`create_default` only works for top-level factory associations.** `create_default(:user)` sets a thread-local default so that any factory calling `user` (top-level association) reuses the existing record. However, it does NOT intercept associations defined inside traits — if a trait defines `address` which itself has a `user` association, `create_default(:user)` won't prevent the cascade. For trait cascades, eliminate the trait instead.
+
+## Red Flags
+
+### `let_it_be` / `before_all` safety
+
+| Pattern | Why | Fix |
+|---------|-----|-----|
+| `let(:x) { create(...) }` for static data | N examples = N unnecessary DB writes | `let_it_be` (check pre-conversion checklist above) |
+| `before { create(...) }` for static setup | Same — runs per example | `before_all` |
+| `let_it_be` redefined in nested context | Evaluated once at load time — redefining is fragile and may not override as expected | Use `let` for values that vary per context |
+| `let_it_be(:x)` where a dependency is overridden via `let` in nested contexts | Record was created with the ORIGINAL dependency — nested overrides are invisible, causing silent wrong-data bugs | Keep the entire dependency chain as `let` |
+| `let_it_be` object referenced by nested `create` with a unique constraint | Shared object persists across contexts; nested creates hit duplicate-entry errors on the unique index | Use `let` for the parent object in those contexts |
+| Top-level `let!` → `let_it_be` when nested contexts redefine the same name with different associations | The `let_it_be` record persists in DB and is still associated with shared parents; nested `let(:name)` shadows the Ruby variable but the DB record is still there, polluting queries that count or filter by association | Keep as `let!` when the name is redefined in nested contexts AND the record is associated with a shared parent |
+| `before_all` or `let_it_be` factory that writes to Redis/cache | DB transaction savepoints don't roll back cache — later examples see stale state | Use `before`/`let`, or add explicit cache cleanup in `after` |
+| `before_all` creating records that reference data overridden in sibling contexts | `before_all` records persist across sibling contexts; if a sibling overrides a dependency, the `before_all` records still reference the original — causing wrong counts or wrong associations (see example below) | Keep as `before` when sibling contexts override any data used in the setup |
+| `let_it_be(:record)` without `refind: true` when sibling contexts load associations on the same object | Association cache persists on the Ruby object even after DB records are rolled back — next context gets stale cached data instead of querying DB | Use `let_it_be(:record, refind: true)` to get a fresh Ruby object per example |
+| `before_all` / `let_it_be` factory on a model with `before_commit`/`after_commit` callbacks that create OTHER records | Callback-created records are committed outside the savepoint — they persist across examples and cause `RecordNotUnique` when a nested `let_it_be` tries to create the same record | Find the callback-created record instead of creating a duplicate: `Model.find_by!(...).tap { \|m\| m.update_columns(...) }` |
+| `travel_to` or `freeze_time` inside `before_all` | Time stays frozen across all examples and leaks to other spec files | Use `before { travel_to(...) }` or block form |
+
+**`before_all` sibling leak example:**
+
+```ruby
+# WRONG — before_all records leak into sibling context that overrides the parent
+context "when filtering posts" do
+  let_it_be(:user) { create(:user, :active) }
+
+  before_all do
+    create_list(:post, 2, user: user)  # created with :active user
+  end
+
+  it "returns 2 posts" do ... end  # passes
+
+  context "when user is suspended" do
+    let(:user) { create(:user, :suspended) }
+    # before_all posts still point to the ORIGINAL :active user!
+    it "returns 0 posts for suspended user" do ... end  # FAILS
+  end
+end
+
+# RIGHT — keep as `before` so each context gets its own records
+  before do
+    create_list(:post, 2, user: user)
+  end
+```
+
+**Mock-leak example:**
+
+```ruby
+# WRONG — mock set up in before_all persists past its example,
+# raising "leaked into another example" errors
+before_all do
+  create(:subscription, user: user)
+  allow(PaymentGateway).to receive(:charge).and_return(success)
+end
+
+# RIGHT — records in before_all, mocks in before
+before_all { create(:subscription, user: user) }
+before { allow(PaymentGateway).to receive(:charge).and_return(success) }
+```
+
+## Escalation Ladder
+
+`let_it_be` → `let_it_be(refind: true)` → `let` → `before { create(...) }` (last resort)
+
+**Conversion broke tests? Diagnose by symptom:**
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| `RecordNotUnique` / duplicate entry | Model callback (`before_commit`, `after_commit`) implicitly creates records that survive the savepoint | Find the callback-created record instead of creating a duplicate: `Model.find_by!(...).tap { \|m\| m.update_columns(...) }` |
+| Stale data / wrong attribute values | Same Ruby object reused across examples; mutations or association cache persist | Add `refind: true` to get a fresh object per example |
+| Wrong associations / unexpected counts | Dependency in the chain is overridden in nested contexts but `let_it_be` record was created with original | Keep entire dependency chain as `let` |
+| `leaked into another example` error | Mocks or doubles used inside `let_it_be` / `before_all` | Move mocks to `before`, keep `let_it_be` for DB records only |
+| Unique constraint in nested context | Nested `create` conflicts with persistent `let_it_be` record on same unique index | Use `let` for the parent object in those contexts |

data/lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/parallel-ci.md

@@ -0,0 +1,77 @@
+# Parallel CI: runner choice and setup
+
+## Runner choice matters
+
+- **`parallel_tests`** splits *files* across processes up front (static). The
+  slowest file becomes the bottleneck and each worker boots the app separately.
+- **`test-queue`** (preferred) forks workers after one boot and hands out
+  examples from a shared queue — a free worker grabs the next spec, so slow
+  files can't strand a worker, and there's no per-worker re-boot. This is what
+  Rails' own Minitest `parallelize` does (fork + distribute), which is why a
+  Minitest suite often looks "faster" than a single-process RSpec — it's the
+  parallelism, not the framework.
+
+## Per-worker databases
+
+Give each worker its own database so workers never contend — but the setup
+differs by runner:
+
+- **`test-queue`** does NOT set `TEST_ENV_NUMBER` (its env vars, e.g.
+  `TEST_QUEUE_WORKERS`, control the queue, not worker identity) — it forks
+  after boot, so workers inherit the parent's DB connection. The stock
+  `rspec-queue` binary has no per-worker hooks; wire a custom runner and
+  reconnect in `after_fork`:
+
+  ```ruby
+  #!/usr/bin/env ruby
+  # bin/test-queue — run as: bin/test-queue spec
+  require "test_queue"
+  require "test_queue/runner/rspec"
+
+  class Runner < TestQueue::Runner::RSpec
+    def after_fork(num)
+      db = ActiveRecord::Base.connection_db_config.configuration_hash
+      ActiveRecord::Base.establish_connection(db.merge(database: "#{db[:database]}_#{num}"))
+    end
+  end
+
+  Runner.new.execute
+  ```
+
+  Create/load the per-worker schemas once in CI setup before the run.
+
+- **`parallel_tests`** sets `TEST_ENV_NUMBER` per process: suffix the database
+  name with it in `database.yml` (SQLite: one file per number), and create the
+  databases with `rake parallel:create parallel:load_schema`.
+
+## Shared cache stores under parallel workers
+
+With a shared store (`:redis_cache_store`, memcached) in test, one worker's
+`Rails.cache.clear` wipes every other worker's entries. Namespace the store
+per worker first, then clear:
+
+```ruby
+# config/environments/test.rb
+config.cache_store = :redis_cache_store,
+  { namespace: "test#{ENV.fetch("TEST_ENV_NUMBER", "")}" }
+
+# spec/rails_helper.rb
+config.after { Rails.cache.clear }
+```
+
+Under `test-queue` nothing sets `TEST_ENV_NUMBER` — assign it in the custom
+runner's `after_fork` above (`ENV["TEST_ENV_NUMBER"] = num.to_s`) so the same
+namespacing works there.
+
+## CI sizing
+
+Know your core count first (GitHub-hosted **private** repos get 2 vCPUs,
+public get 4) — cache the runtime log for runtime-based balancing.
+
+## Fair queues expose isolation bugs — that's a feature
+
+**A fair queue exposes every latent isolation bug** — specs that only passed
+because another file ran first in the same process. It finds real
+order-dependence. When a spec fails only under parallelism, run it *alone*
+(`rspec path/to/x_spec.rb`) — if it fails there too, it's a self-sufficiency
+bug (a missing `require`/constant, or leaked global state), not the runner.

data/lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/profiling.md

@@ -0,0 +1,24 @@
+# Profiler Cheat-sheet (test-prof)
+
+Run against one file (or a directory) — profiling a whole suite drowns the signal:
+
+| Command | Tool | Answers |
+|---|---|---|
+| `FPROF=1 bundle exec rspec <path>` | FactoryProf | per-factory create counts; `total` ≫ `top-level` = cascade |
+| `FACTORY_DEFAULT_PROF=1 bundle exec rspec <path>` | FactoryDefault prof | which implicit associations `create_default` could share |
+| `EVENT_PROF='sql.active_record' bundle exec rspec <path>` | EventProf | time spent in SQL (is it even the bottleneck?) |
+| `EVENT_PROF='factory.create' bundle exec rspec <path>` | EventProf | share of time in factories |
+| `RD_PROF=1 bundle exec rspec <path>` | RSpecDissect | `before`-hook time vs example-body time, slowest groups |
+| `TPS_PROF=1 bundle exec rspec <path>` | TPS profiler | files with the most shared-setup overhead per example (best `let_it_be` candidates) |
+| `TEST_MEM_PROF=gc bundle exec rspec <path>` | Memory profiler | examples contributing most to GC time |
+| `TEST_STACK_PROF=1 bundle exec rspec <path>` | StackProf | CPU flamegraph of the hottest code paths |
+| `bundle exec rspec --profile 10 <path>` | RSpec | slowest 10 examples |
+| `bundle exec rspec --seed <N> --bisect <path>` | RSpec | minimal failing example pair for an order-dependence |
+
+Start with `EVENT_PROF`/`FPROF` to confirm *where* time goes before optimizing —
+if SQL is ~10% and factories are a third, don't chase N+1s.
+
+Each profiler also ships as a slash command the user can invoke directly
+(`/fprof`, `/event-prof`, `/rd-prof`, `/tps-prof`, `/factory-default-prof`,
+`/mem-prof`, `/stack-prof`, plus `/slowest-specs` and `/bisect-order`) — when
+suggesting a profiling step to the user, point them at the command.

data/lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/structure.md

@@ -0,0 +1,45 @@
+# Spec Ordering Convention (test-prof)
+
+Within each `describe`/`context` block, declarations follow this order:
+
+1. `subject` — named (`subject(:result) { ... }`) whenever examples reference it; bare only for `is_expected` one-liners
+2. `let_it_be` — static data (created once)
+3. `let` / `let!` — per-context overrides
+4. `before_all` — static setup (no mocks)
+5. `before` — per-example setup (mocks, stubs)
+6. Examples (`it` / `specify`)
+7. Nested `context` blocks
+
+```ruby
+RSpec.describe MyService, type: :service do
+  subject(:result) { described_class.call(user: user, params: params) }
+
+  # 1. Static data (let_it_be)
+  let_it_be(:user) { create(:user) }
+  let_it_be(:account) { create(:account) }
+
+  # 2. Per-context data (let) — only when overridden below
+  let(:params) { { name: "test" } }
+
+  # 3. Static setup (before_all)
+  before_all do
+    create(:membership, user:, account:, role: "owner")
+  end
+
+  # 4. Per-example setup (before) — only for mocks or mutable state
+  before do
+    allow(ExternalApi::Client).to receive(:call).and_return(success_response)
+  end
+
+  # 5. Tests
+  it "does the thing" do
+    expect(result).to ...
+  end
+
+  context "when condition varies" do
+    let(:params) { { name: "" } }  # override is why this uses let
+
+    it "handles the edge case" do ...
+  end
+end
+```

data/lib/rails-hyperdrive-martian-spec/version.rb

@@ -0,0 +1,3 @@
+module RailsHyperdriveMartianSpec
+  VERSION = "0.3.1"
+end

data/lib/rails-hyperdrive-martian-spec.rb

@@ -0,0 +1,4 @@
+require "rails-hyperdrive-martian-spec/version"
+
+module RailsHyperdriveMartianSpec
+end

metadata

@@ -0,0 +1,71 @@
+--- !ruby/object:Gem::Specification
+name: rails-hyperdrive-martian-spec
+version: !ruby/object:Gem::Version
+  version: 0.3.1
+platform: ruby
+authors:
+- izhanov
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies: []
+description: |
+  Companion gem for rails-hyperdrive. Ships the `martian-spec` skill — a procedural,
+  model-invoked guide for writing RSpec specs in Rails projects. Installed lazily
+  by `bin/rails hyperdrive:init` into `.claude/skills/martian-spec/SKILL.md`.
+email:
+- aibek.izhanov@evilmartians.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE.txt
+- README.md
+- commands/bisect-order.md
+- commands/event-prof.md
+- commands/factory-default-prof.md
+- commands/fprof.md
+- commands/mem-prof.md
+- commands/profile-specs.md.erb
+- commands/rd-prof.md
+- commands/slowest-specs.md
+- commands/stack-prof.md
+- commands/tps-prof.md
+- hyperdrive.yml
+- lib/rails-hyperdrive-martian-spec.rb
+- lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/SKILL.md.erb
+- lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/data-setup.md
+- lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/parallel-ci.md
+- lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/profiling.md
+- lib/rails-hyperdrive-martian-spec/hyperdrive/skills/martian-spec/references/structure.md
+- lib/rails-hyperdrive-martian-spec/version.rb
+homepage: https://github.com/izhanov/rails-hyperdrive-martian-spec
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/izhanov/rails-hyperdrive-martian-spec
+  source_code_uri: https://github.com/izhanov/rails-hyperdrive-martian-spec
+  changelog_uri: https://github.com/izhanov/rails-hyperdrive-martian-spec/blob/main/CHANGELOG.md
+  allowed_push_host: https://rubygems.org
+  rubygems_mfa_required: 'true'
+  hyperdrive_targets: rspec-rails
+  hyperdrive_artifacts: skill,command
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.2.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.6
+specification_version: 4
+summary: 'Rails Hyperdrive companion gem: RSpec skill for AI coding agents.'
+test_files: []