@mrciphersmith/keryx 0.3.1 → 0.3.3

package/src/gdskills/bundled/stacks/ruby-rails/governance/scout.json

@@ -0,0 +1,33 @@
+[
+  {
+    "query": "Use when implementing or extending a feature in a Ruby on Rails app -- MVC boundaries, strong parameters, ActiveRecord associations and scopes, service objects for fat controllers/models, ActiveJob, and modern Ruby 3.x idiom (pattern matching, endless methods, keyword args).",
+    "decision": "create",
+    "topMatch": "ruby-rails/ruby-rails-testing",
+    "recordedAt": "2026-09-25T15:28:04.114Z",
+    "skillName": "ruby-rails-implementation"
+  },
+  {
+    "query": "Use when a Rails app's test suite needs writing, extending, or fixing -- RSpec request/model/job specs (or Minitest equivalents), FactoryBot fixtures, stubbing external HTTP calls, asserting on enqueued ActiveJobs, and avoiding sleep-based waits.",
+    "decision": "fork",
+    "topMatch": "php-laravel/php-laravel-testing",
+    "recordedAt": "2026-09-25T15:28:28.999Z",
+    "skillName": "ruby-rails-testing",
+    "justification": "Nearest match php-laravel/php-laravel-testing (0.32) covers PHPUnit/Pest specs, Laravel factories, and PHP HTTP mocking -- not RSpec/Minitest syntax, FactoryBot, or ActiveJob's have_enqueued_job/perform_enqueued_jobs test helpers. react/react-testing (0.23) and python/python-testing (0.21) are further still, sharing only generic testing vocabulary. None share Rails-specific test vocabulary (RSpec, FactoryBot, ActiveJob, request specs) so this is a genuine fork, not a substitute."
+  },
+  {
+    "query": "Use when bundle install/bundle exec fails, a Rails migration or db:test:prepare fails, rubocop reports offenses, or a Rails test suite fails to boot -- resolves Gemfile.lock mismatches, pending/failed migrations, autoload/zeitwerk errors, and rubocop findings with the smallest root-cause fix.",
+    "decision": "fork",
+    "topMatch": "php-laravel/php-laravel-build-fix",
+    "recordedAt": "2026-09-25T15:28:36.534Z",
+    "skillName": "ruby-rails-build-fix",
+    "justification": "Nearest matches: php-laravel/php-laravel-build-fix (0.44) fixes Composer/artisan migration and PHP linter failures, not Bundler/Gemfile.lock, ActiveRecord migrations, or Zeitwerk autoload errors. go/go-build-fix (0.26) and python/python-build-fix (0.24) fix their own compiler/module-toolchain surfaces, unrelated to rubocop or db/schema.rb regeneration. None share Ruby/Rails-specific vocabulary (Bundler, Zeitwerk, rubocop, db:test:prepare) so this is a genuine fork, not a substitute."
+  },
+  {
+    "query": "Use when reviewing a Rails change for framework-specific risks -- mass assignment gaps, N+1 queries, raw SQL interpolation, raw/html_safe XSS, missing auth/authorization filters, fat controllers/models, and non-idempotent ActiveJobs. Not for a change in another web framework's own MVC layer (use that framework's own code-review skill). Read-only, no edits.",
+    "decision": "fork",
+    "topMatch": "php-laravel/php-laravel-code-review",
+    "recordedAt": "2026-09-25T18:46:59.677Z",
+    "skillName": "ruby-rails-code-review",
+    "justification": "Nearest match php-laravel-code-review (0.38) shares generic web-framework risk vocabulary (mass assignment, N+1, raw SQL) but reviews Laravel/Eloquent/Blade-specific APIs ($fillable/$guarded, VerifyCsrfToken, ShouldBeUnique) with no knowledge of Rails' strong_parameters, ActiveRecord query interface, or ERB escaping; a reviewer following the Laravel skill could not name the right file/line pattern in a Rails diff. This pack has no lang:ruby skill to extend and is the first Rails reviewer in the catalog, so this is a genuine fork, not a substitute."
+  }
+]

package/src/gdskills/bundled/stacks/ruby-rails/pack.json

@@ -0,0 +1,42 @@
+{
+  "id": "ruby-rails",
+  "family": "framework",
+  "modules": ["ruby-rails-rules", "ruby-rails-skills"],
+  "detectionMarkers": ["ruby", "rails"],
+  "provenance": {
+    "origin": "authored",
+    "sourceRef": "flow 337, Wave 4 batch 5"
+  },
+  "stability": "experimental",
+  "skills": {
+    "implement": ["ruby-rails-implementation"],
+    "test": ["ruby-rails-testing"],
+    "review": ["ruby-rails-code-review"],
+    "build-fix": ["ruby-rails-build-fix"],
+    "migrate": []
+  },
+  "agentProfile": {
+    "displayName": "Ruby on Rails",
+    "auditFocus": [
+      "a controller action that builds a model from raw params without strong parameters (params.expect/params.require+permit), enabling mass assignment",
+      "raw SQL built with string interpolation instead of ActiveRecord parameterized conditions or sanitize_sql",
+      "a loop over an association that triggers N+1 queries because includes/preload/eager_load was not used",
+      "raw/html_safe applied to a value that can contain user input, bypassing ERB's automatic HTML escaping",
+      "a controller action reachable without before_action :authenticate_user! (or the app's equivalent) or an authorization check",
+      "an ActiveJob whose perform is not safe to run twice (no idempotency key or guard) on an adapter that can redeliver it -- true of most production Active Job adapters",
+      "a credential, API key, or signing secret committed in source instead of Rails credentials or ENV"
+    ],
+    "buildCommands": [
+      "bundle exec rspec (or bin/rails test, whichever the project uses)",
+      "bundle exec rubocop",
+      "bin/rails db:test:prepare (when a migration changed the schema)",
+      "bundle exec brakeman -q (only when the project has Brakeman configured)"
+    ],
+    "fixGuardrails": [
+      "Never add rubocop:disable to silence an offense instead of fixing the underlying code.",
+      "Never edit db/schema.rb by hand to make a migration pass; fix or add the migration and re-run it.",
+      "Never loosen strong parameters (e.g. permit!) or drop a before_action authentication/authorization filter just to make a failing request test pass.",
+      "Never delete or skip a failing test to reach a green build."
+    ]
+  }
+}

package/src/gdskills/bundled/stacks/ruby-rails/rules/coding-style.mdc

@@ -0,0 +1,69 @@
+---
+extends: common
+paths: ["**/*.rb"]
+metadata:
+  origin: authored
+---
+
+# Ruby on Rails coding style
+
+Narrows `core-common-rules`' stack-agnostic style rules to modern Ruby
+(3.x) idiom and Rails conventions in one pack (this pack has no separate
+`lang:ruby` base to extend). Applies only to `*.rb` files.
+
+## Naming and structure
+
+- `snake_case` for methods, local variables, file names, and DB
+  columns/tables; `CamelCase` for classes and modules — never mix Ruby's
+  own convention with a borrowed one from another language.
+- A predicate method (returns true/false) ends in `?` (`published?`, not
+  `is_published`); a destructive/bang method that mutates in place or
+  raises instead of returning nil ends in `!` and normally has a
+  non-bang counterpart (`save!` alongside `save`).
+- Two-space indentation, no tabs; keep a method short enough to read on
+  one screen — a model method past ~10 lines is a signal to extract a
+  private method, a concern, or (per `rules/patterns.mdc`) a service
+  object, not to keep growing in place.
+- Follow the app's own file layout: `app/models`, `app/controllers`,
+  `app/jobs`, `app/services` (if the app already has one) — do not
+  invent a new top-level directory for one class.
+
+## Modern Ruby (3.x) idiom
+
+- Reach for `case/in` pattern matching when destructuring a
+  hash/array-shaped value (parsed JSON, a multi-branch conditional on a
+  value's shape) reads clearer than a chain of `if`/`elsif` or
+  `dig`/`fetch` calls; do not force pattern matching onto a simple
+  `if value.nil?` check where it adds no clarity.
+- An endless method (`def full_name = "#{first_name} #{last_name}"`) is
+  fine for a genuine one-expression method; do not squeeze a
+  multi-statement method onto one line just to use the syntax.
+- Keyword arguments (`def initialize(name:, email:)`) for a method with
+  more than one or two parameters, especially when some are optional —
+  clearer at the call site than positional args, and safer against
+  argument-order mistakes than a trailing options hash.
+- Prefer `Data.define`/a plain `Struct` for a small immutable value
+  object over a full `ActiveRecord`-backed model when nothing needs
+  persisting.
+- Safe navigation (`user&.profile&.bio`) only where `nil` is an expected,
+  legitimate state for the chain; do not use it to paper over a case
+  where a `nil` actually signals a bug that should raise or be handled
+  explicitly.
+
+## Frozen string literals and immutability
+
+- New Ruby files start with `# frozen_string_literal: true` (match the
+  project's own convention if it already has one) — string literals are
+  frozen by default, so any `String#<<`/`gsub!`/`concat` mutation must
+  target an explicit `.dup`/`String.new`, not a literal.
+- Prefer returning a new value over mutating an argument in place, except
+  for methods whose name signals mutation (`!`-suffixed, or a
+  conventionally mutating method like `each`'s block).
+
+## Formatting and linting
+
+- Match whatever the project's own `.rubocop.yml` enforces; do not
+  hand-format around a configured linter or introduce a style the
+  project's cops would flag.
+- Run `bundle exec rubocop` (scoped to changed files is fine during
+  iteration) before considering a change formatted correctly.

package/src/gdskills/bundled/stacks/ruby-rails/rules/patterns.mdc

@@ -0,0 +1,93 @@
+---
+extends: common
+paths: ["**/*.rb", "**/*.erb"]
+metadata:
+  origin: authored
+---
+
+# Ruby on Rails patterns
+
+Narrows `core-common-rules`' stack-agnostic design guidance to idiomatic
+Rails application design and its common anti-patterns. Applies to
+`*.rb` and `*.erb` files.
+
+## MVC boundaries
+
+- A controller action orchestrates: it reads params, calls into a
+  model/service, and renders/redirects — it does not contain business
+  logic (validation rules, multi-step workflows, external API calls)
+  inline in the action body.
+- A view renders presentation only; move any non-trivial conditional or
+  data-shaping logic in a view into a helper or a presenter/decorator
+  object instead of embedded Ruby blocks doing real work.
+- `ApplicationRecord` models hold persistence concerns (validations,
+  associations, scopes) and behavior that genuinely belongs to the
+  record itself; a model accumulating callbacks that orchestrate
+  unrelated side effects (send an email, call a third-party API, update
+  a different model) is a "fat model" — extract that orchestration into
+  a service object or an `ActiveJob`.
+
+## Concerns
+
+- A `Concern` (`app/models/concerns`, `app/controllers/concerns`) should
+  bundle genuinely reusable, cohesive behavior shared by more than one
+  class — not become a dumping ground for one model's unrelated methods
+  split out just to shrink the file. If nothing else in the app is ever
+  going to `include` it, it is not a concern, it is the class's own
+  method.
+- Name a concern for the *capability* it adds (`Archivable`,
+  `Sluggable`), not for the model it happens to have been extracted
+  from.
+
+## Service objects and fat controllers/models
+
+- When an action's logic spans multiple models, calls an external
+  service, or has enough branching to need its own tests independent of
+  the controller, extract a plain Ruby service object (a
+  `SomethingVerb` class with one public entry point, e.g. `.call`) that
+  the controller/model delegates to — do not grow the controller action
+  or a model callback to hold it, and match the app's own existing
+  service-object convention (directory, base class, `.call` vs `#call`)
+  if one already exists rather than inventing a second style.
+- A service object should be easy to unit test without spinning up a
+  full request — keep framework concerns (params, session, rendering)
+  out of it; pass it plain values or model instances instead.
+
+## ActiveRecord query patterns
+
+- Eager-load an association before iterating over it in a loop
+  (`Book.includes(:author)`), not after the N+1 has already happened —
+  prefer `includes` (Rails picks `preload` or `eager_load` for you) over
+  hand-choosing one of the lower-level methods unless you have a
+  specific reason to force one.
+- Push filtering/aggregation into the database (`where`, `group`,
+  `count`, a named `scope`) rather than loading full ActiveRecord
+  objects into Ruby and filtering/reducing them in memory.
+- A named `scope` (`scope :published, -> { where(published: true) }`)
+  for a query fragment reused in more than one place, instead of
+  copy-pasting the same `where` clause across controllers/models.
+
+## Background jobs
+
+- An `ActiveJob` should be idempotent — most production queue adapters
+  (Sidekiq, SQS) are at-least-once, so a retried or duplicated job run must not
+  double-charge, double-send, or otherwise corrupt state; guard with a
+  uniqueness check, an idempotency key, or an upsert instead of assuming
+  `perform` runs exactly once.
+- Pass simple identifiers (an id) into a job's `perform`, not a whole
+  ActiveRecord object — the record can change or be deleted between
+  enqueue and execution (GlobalID serializes it, but the job should
+  re-fetch and handle a missing record rather than trust a stale copy).
+
+## Anti-patterns to flag
+
+- A "fat controller" action with inline business logic, or a "fat
+  model" whose callbacks orchestrate unrelated side effects — extract a
+  service object per above.
+- A concern used purely to split up one class's file size rather than to
+  share real behavior.
+- Raw SQL string interpolation instead of ActiveRecord's parameterized
+  query interface or `sanitize_sql` (see `rules/security.mdc`).
+- A `default_scope` that silently changes every query against a model —
+  usually surprising at a call site far from the model definition;
+  prefer an explicit named scope callers opt into.

package/src/gdskills/bundled/stacks/ruby-rails/rules/security.mdc

@@ -0,0 +1,90 @@
+---
+extends: common
+paths: ["**/*.rb", "**/*.erb"]
+metadata:
+  origin: authored
+---
+
+# Ruby on Rails security
+
+Narrows `core-common-rules`' stack-agnostic security rules to
+Rails-specific, OWASP-relevant risks and the safe framework API to use
+instead. Applies to `*.rb` and `*.erb` files.
+
+## Mass assignment and strong parameters
+
+- Never build or update a model from a raw `params` hash
+  (`Model.new(params[:model])`, `record.update(params)`); require the
+  permitted shape first with `params.expect(model: [:field, ...])`
+  (current Rails idiom) or `params.require(:model).permit(:field, ...)`,
+  and never call `permit!` on user-controlled params — it disables
+  strong parameters entirely and lets any attacker-supplied key through,
+  including ones like `admin`/`role` that were never meant to be
+  user-settable.
+- List every permitted attribute explicitly; do not permit a whole
+  nested hash with a bare `permit(:nested)` when only specific
+  sub-keys should be writable.
+
+## SQL and data access
+
+- Use ActiveRecord's parameterized conditions (`where("age > ?", age)`,
+  `where(age: age)`, or named placeholders) — never
+  string-interpolate a user-influenced value into `where`,
+  `find_by_sql`, `order`, or any other query method
+  (`where("name = '#{params[:name]}'")` is SQL injection).
+- When raw SQL genuinely cannot be avoided (a fragment passed to
+  `order`/`pluck` built from a dynamic column list, for instance), pass
+  untrusted values through `ActiveRecord::Base.sanitize_sql`/
+  `sanitize_sql_array`, never through direct string interpolation.
+
+## Output encoding and XSS
+
+- Rely on ERB's automatic HTML escaping for any value that can contain
+  user input; using `raw(value)` or `value.html_safe` on
+  user-controlled or user-influenced content reintroduces XSS by
+  marking untrusted text as pre-escaped. Reserve `raw`/`html_safe` for
+  genuinely static, developer-authored content, and prefer a sanitizer
+  (`sanitize`) over `html_safe` when some user-supplied markup must be
+  allowed through.
+
+## Authentication and authorization
+
+- Every controller action that requires a logged-in user runs a
+  `before_action` (e.g. `:authenticate_user!` or the app's own
+  equivalent) — an action added to an already-protected controller
+  inherits the filter only if it is not explicitly skipped
+  (`skip_before_action`); check that a new action was not accidentally
+  excluded.
+- Authentication (who is this) is not authorization (what can they do):
+  confirm the current user is allowed to act on *this specific* record
+  (ownership/role check), not just that they are logged in at all —
+  an unauthorized action on someone else's resource (IDOR) is a
+  distinct bug from a missing login check.
+
+## CSRF
+
+- Keep `protect_from_forgery with: :exception` (or the equivalent
+  `ActionController::Base` default) enabled for any controller serving
+  browser-submitted forms; do not disable CSRF protection
+  (`skip_before_action :verify_authenticity_token`,
+  `protect_from_forgery with: :null_session`) on an action reachable
+  from a standard HTML form just to make a request easier to test or
+  call from a script — scope any real exception (a webhook endpoint
+  verified by its own signature, for instance) as narrowly as possible
+  and say why in the change.
+
+## Background jobs
+
+- An `ActiveJob` must tolerate being run more than once for the same
+  logical unit of work (most production queue adapters are at-least-once) —
+  guard non-idempotent side effects (charging a card, sending an email)
+  with a uniqueness check or an idempotency key rather than assuming
+  single delivery.
+
+## Secrets
+
+- Never commit a credential, API key, or signing secret in source —
+  store it in Rails encrypted credentials (`bin/rails credentials:edit`)
+  or an environment variable the deployment already manages, and load it
+  through `Rails.application.credentials`/`ENV`, not a literal in a
+  `.rb` file.

package/src/gdskills/bundled/stacks/ruby-rails/rules/testing.mdc

@@ -0,0 +1,89 @@
+---
+extends: common
+paths: ["**/*.rb"]
+metadata:
+  origin: authored
+---
+
+# Ruby on Rails testing
+
+Narrows `core-common-rules`' stack-agnostic testing rules to Rails
+testing idiom. Covers RSpec (the more common choice in current Rails
+apps) and notes the Minitest equivalent where it differs meaningfully.
+Applies only to `*.rb` files.
+
+## Layout and framework choice
+
+- Match whichever framework the project already uses — `spec/` with
+  RSpec (`*_spec.rb`) or `test/` with Minitest (`*_test.rb`); do not
+  introduce the other framework into a project that has standardized on
+  one.
+- Mirror `app/`'s structure under `spec/`/`test/`: a model at
+  `app/models/order.rb` gets a spec at `spec/models/order_spec.rb`, a
+  job at `app/jobs/charge_job.rb` gets
+  `spec/jobs/charge_job_spec.rb`, and so on.
+
+## RSpec conventions
+
+- `describe`/`context`/`it` read as a sentence — `context` for a
+  precondition ("when the user is not signed in"), `it` for the
+  observable behavior ("redirects to the login page"); avoid vague
+  `it "works"` descriptions.
+- Use `let`/`let!` for lazily/eagerly built fixtures shared across
+  examples in a block instead of repeating setup in every `it`;
+  `before` blocks for side effects that must run before each example.
+- Request specs (`spec/requests`) exercise a controller action through
+  the full stack (routing, before_actions, rendering) and are generally
+  preferred over controller specs for new Rails apps; system specs
+  (`spec/system`, via Capybara) exercise a full browser flow — pick the
+  narrowest layer that actually covers what changed.
+- Use FactoryBot (`create`/`build`, `build_stubbed` when persistence
+  isn't needed) if the project already has it configured, matching its
+  existing factory definitions rather than hand-building fixtures a
+  different way.
+
+## Minitest conventions (when the project uses it instead)
+
+- `test "does something" do ... end` inside a `class XyzTest <
+  ActiveSupport::TestCase` (or `ActionDispatch::IntegrationTest` for
+  request tests); fixtures come from `test/fixtures/*.yml` or the
+  project's own factory setup.
+- Assertions read `assert_equal expected, actual` (expected first) and
+  `assert_predicate`/`assert_raises` over a bare `assert` on a boolean
+  expression, for a clearer failure message.
+
+## Database and external boundaries
+
+- Tests run inside a transaction per example (RSpec's
+  `use_transactional_fixtures`/Rails' default Minitest behavior) that
+  rolls back automatically — do not manually clean up records created
+  in a test unless the app has opted out of transactional tests for a
+  specific reason (e.g. system specs across threads), in which case
+  match whatever cleanup strategy (DatabaseCleaner, truncation) it
+  already uses.
+- Stub/mock an external HTTP call (a third-party API, a webhook) at the
+  boundary (WebMock, VCR cassettes, or the project's existing tooling)
+  — a test must not make a real network call.
+- Assert an `ActiveJob` was enqueued with `have_enqueued_job`
+  (RSpec) / `assert_enqueued_with` (Minitest) rather than asserting on
+  its side effects by actually running it, unless the test's purpose is
+  specifically to exercise the job's `perform` behavior — in which case
+  drain the queue explicitly (`perform_enqueued_jobs`) instead of
+  sleeping or polling for it to run.
+
+## Determinism
+
+- Never synchronize with `sleep` to wait for a background job, an
+  async callback, or an eventually-consistent read — use
+  `perform_enqueued_jobs`, a Capybara-provided wait matcher
+  (`have_content` retries automatically), or an explicit polling helper
+  with a timeout.
+- Freeze time (`travel_to`/`Timecop`, matching whatever the project
+  already uses) for any test asserting on a timestamp or a
+  time-dependent calculation, instead of asserting against
+  `Time.current` computed twice and racing a clock tick.
+
+## Regression discipline
+
+- A bug fix gets a regression test that fails before the fix and passes
+  after; new behavior gets new coverage in the same change.

package/src/gdskills/bundled/stacks/ruby-rails/skills/ruby-rails-build-fix/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: ruby-rails-build-fix
+description: "Use when bundle install/bundle exec fails, a Rails migration or db:test:prepare fails, rubocop reports offenses, or a Rails test suite fails to boot -- resolves Gemfile.lock mismatches, pending/failed migrations, autoload/zeitwerk errors, and rubocop findings with the smallest root-cause fix."
+triggers:
+  - "bundle install is failing"
+  - "this Rails migration won't run"
+  - "rubocop is reporting offenses on this Rails file"
+  - "zeitwerk autoloading error in this Rails app"
+  - "Gemfile.lock is out of sync"
+  - "Rails test suite won't boot, pending migration"
+metadata:
+  origin: authored
+  category: build-fix
+  version: "1.0.0"
+  compatible_harnesses: "claude,codex,cursor,zed,opencode"
+license: "MIT"
+---
+
+# Ruby on Rails build fix
+
+Resolve a `bundle install`/`bundle exec` failure, a pending or failing
+migration, a Zeitwerk autoload error, a `rubocop` finding, or a Rails
+test suite that fails to boot — with the smallest change that fixes the
+actual root cause. `rules/coding-style.mdc` and `rules/security.mdc`
+govern what a "correct" fix looks like; this skill never reaches for a
+suppression instead of a fix.
+
+## Workflow
+
+### Step 1: Reproduce and classify
+
+```bash
+bundle install
+bundle exec rubocop
+bin/rails db:migrate:status
+```
+
+Read the exact error text and classify it:
+
+- **Bundler/Gemfile.lock mismatch** (`Gemfile.lock` doesn't satisfy
+  `Gemfile`, a version conflict, a missing platform entry).
+- **Pending/failing migration** (`db:migrate:status` shows `down`
+  entries, or `db:migrate` raises).
+- **Zeitwerk autoload error** (`Zeitwerk::NameError`, a file whose
+  constant name doesn't match its path).
+- **Rubocop offense** (a cop violation reported by `bundle exec
+  rubocop`).
+- **Test suite boot failure** (the suite errors before any example
+  runs — usually a load error, a missing fixture/factory, or a schema
+  mismatch against `db/test.sqlite3`/the test database).
+
+### Step 2: Fix by category
+
+**Bundler/Gemfile.lock:** run `bundle install` first — if it reports a
+real version conflict rather than a simple stale lock, check `bundle
+outdated <gem>` and the Gemfile's version constraints before bumping a
+version by hand. Only edit `Gemfile.lock` by running Bundler commands
+against it, never by hand-editing the lock file's resolved versions.
+
+**Pending/failing migration:** run `bin/rails db:migrate` to apply a
+genuinely pending migration. For a migration that raises, fix the
+migration itself (a bad column type, a missing `up`/`down` pair) and
+re-run it — never hand-edit `db/schema.rb` to match what the migration
+was supposed to produce; the schema is generated, not authored. Run
+`bin/rails db:test:prepare` afterward so the test database matches.
+
+**Zeitwerk autoload error:** match the file's path to its expected
+constant name (`app/models/order_item.rb` must define `OrderItem`, not
+`OrderItem` inside a wrongly-cased directory, or vice versa) — Zeitwerk
+infers the constant from the path. If the class genuinely needs a
+different constant name than its conventional path implies, use an
+explicit `inflect`/custom loader entry in
+`config/initializers/zeitwerk.rb` rather than working around the
+mismatch with a `require` or a `require_relative`.
+
+**Rubocop offense:** fix the code the offense names. Never add
+`# rubocop:disable Cop/Name` (or a blanket disable at the top of the
+file) to silence a finding without fixing or explaining the underlying
+issue in the report — a narrow, justified disable comment is only
+acceptable when the project's own `.rubocop.yml` already documents that
+exception pattern.
+
+**Test suite boot failure:** read the actual load error — a missing
+factory/fixture reference, a schema mismatch (run `bin/rails
+db:test:prepare`), or a require error in `spec_helper.rb`/`rails_helper.rb`.
+Fix the referenced file or run the schema sync; do not comment out the
+failing require or skip loading part of the suite to get past the
+error.
+
+### Step 3: Verify
+
+```bash
+bundle exec rspec   # or: bin/rails test
+bundle exec rubocop
+bin/rails db:migrate:status
+```
+
+All must exit 0 (migrate:status shows no pending migrations) before
+reporting done.
+
+### Step 4: Report
+
+```
+Fixed: pending migration 20260101000000_add_index_to_orders.rb
+  - Root cause: migration was committed but never run against the dev/test DB
+  - Ran bin/rails db:migrate + db:test:prepare; rspec/rubocop both pass
+```
+
+State the root cause in one sentence, not just "fixed the error."
+
+## Rules
+
+- Find and fix the smallest change that addresses the actual root
+  cause — never widen a fix beyond what the failure requires.
+- NEVER add `# rubocop:disable` to silence a finding instead of fixing
+  what it found, unless the project's own config already documents
+  that exception.
+- NEVER hand-edit `db/schema.rb` to make a migration failure disappear
+  — fix or add the migration and let it regenerate the schema.
+- NEVER hand-edit `Gemfile.lock`'s resolved versions directly; use
+  Bundler commands.
+- NEVER delete or skip a failing test to reach a green build.
+
+## Red Flags
+
+| Rationalization | Why it is wrong |
+|---|---|
+| "I'll add `# rubocop:disable Metrics/MethodLength` here so it stops complaining" | Silences the finding without addressing the actual length/complexity issue the cop caught; refactor instead unless the project's config already allows this exception |
+| "I'll just edit db/schema.rb to add the column the migration was supposed to add" | `db/schema.rb` is generated from migrations, not authored directly; a hand-edit drifts from what `db:migrate` actually produces and breaks the next `db:schema:load` |
+| "This gem conflict is annoying, I'll just delete Gemfile.lock and let it regenerate" | Throws away every other gem's pinned, tested version along with the one causing the conflict; resolve the actual constraint instead |
+| "I'll require_relative the file manually to work around the Zeitwerk naming error" | Papers over a path/constant mismatch Zeitwerk will keep re-flagging elsewhere; fix the file's name/location (or the explicit inflection) instead |
+
+## Verification
+
+Do not report the fix done until all of the following hold:
+
+- `bundle exec rspec` (or `bin/rails test`) and `bundle exec rubocop`
+  both exit 0, and `bin/rails db:migrate:status` shows no pending
+  migrations.
+- The change is the smallest one that addresses the stated root cause —
+  no unrelated files touched.
+- The report states the root cause in one sentence, not just "build now
+  passes."

package/src/gdskills/bundled/stacks/ruby-rails/skills/ruby-rails-build-fix/evals.json

@@ -0,0 +1,73 @@
+{
+  "triggers": {
+    "positive": [
+      "After merging main, bundle exec rspec won't even start because Gemfile.lock pins pg to an older version than what's installed",
+      "I pulled a teammate's branch and now rails db:test:prepare errors out because the schema doesn't include their new migration",
+      "rubocop is flagging Metrics/MethodLength on this file, how do I fix it",
+      "Zeitwerk can't find the constant for this file, what's wrong",
+      "The test suite errors before any example runs",
+      "Gemfile.lock doesn't match Gemfile after I added a gem"
+    ],
+    "negative": [
+      "npm install is failing with a peer dependency conflict",
+      "cargo build is failing for this Rust crate",
+      "Implement the feature once the build is fixed",
+      "Review this Rails diff for security issues",
+      "Write a regression test for this migration bug"
+    ]
+  },
+  "scenarios": [
+    {
+      "id": "no-rubocop-disable-suppression",
+      "prompt": "rubocop is flagging Metrics/MethodLength on this method I just wrote. How should I fix it?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer fixes the actual complexity the cop flagged by breaking the method into smaller, well-named pieces (an extracted private method or, for cross-model/external-call orchestration, a service object), rather than silencing the finding with a rubocop:disable comment, whether as the sole fix or as extra headroom after a partial refactor.",
+          "pass_criteria": [
+            "Identifies the fix as breaking the method into smaller pieces (an extracted private method or a service object) to reduce its length/complexity, not merely suppressing the finding.",
+            "Shows a concrete extraction direction (names what sub-step would become its own method or object), not just 'refactor it'.",
+            "Does not rely on rubocop:disable as part of the fix for the flagged finding."
+          ],
+          "fail_criteria": [
+            "Recommends adding a rubocop:disable comment (e.g. `# rubocop:disable Metrics/MethodLength`) -- whether as the sole fix or as extra 'headroom' after a partial refactor -- instead of finishing the refactor so the method satisfies the cop on its own. Mentioning rubocop:disable only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "That cop is telling you the method has grown too long to read in one pass. Look for a natural sub-step -- a chunk of the method that computes one intermediate value or handles one branch -- and pull it into its own well-named private method (or, if it's coordinating several models/external calls, a service object per the project's own pattern). That shrinks the flagged method while keeping each piece testable on its own. Once you've split it up, re-run `bundle exec rubocop` to confirm the cop is actually satisfied, not just that the method looks shorter to you.",
+        "known_wrong": "Quickest fix is to add `# rubocop:disable Metrics/MethodLength` above the method (and `# rubocop:enable` after it, or just leave it disabled for the rest of the file) -- that clears the offense without needing to restructure anything. The method works fine as written; the cop's default threshold is often too strict for methods that just have a lot of straightforward steps in a row.",
+        "vague": "You should probably break that method up a bit instead of just silencing the linter.",
+        "subtle_wrong": "Extract the middle chunk of the method -- the part building the response hash -- into a private method so the main method reads shorter, which should bring the line count close to the limit. If it's still one or two lines over after that, just add `# rubocop:disable Metrics/MethodLength` above the method as a small bit of headroom rather than splitting it further -- you've already done the real work of shrinking it, so a narrow disable for the last couple of lines is a reasonable trade-off."
+      },
+      "anti_patterns": ["rubocop:disable"]
+    },
+    {
+      "id": "no-hand-edit-schema",
+      "prompt": "A migration to add an index failed halfway and now db:test:prepare is failing because the test schema doesn't have it. What should I do?",
+      "strictness": "high",
+      "expected_behavior": [
+        {
+          "grader": "judge",
+          "rubric": "A correct answer treats db/schema.rb as generated output and fixes the root cause by repairing and re-running the migration (bin/rails db:migrate) rather than hand-editing schema.rb to add the missing index, then syncs the test database with db:test:prepare.",
+          "pass_criteria": [
+            "States that the migration itself needs to be fixed and re-run (bin/rails db:migrate) rather than hand-editing schema.rb.",
+            "Names the concrete command sequence: fix the migration, run db:migrate, then db:test:prepare to sync the test database.",
+            "States or implies that db/schema.rb is generated output, not something to author directly."
+          ],
+          "fail_criteria": [
+            "Recommends directly hand-editing schema.rb to add the missing index instead of fixing and re-running the migration. Mentioning that only to warn against it is not a failure."
+          ]
+        }
+      ],
+      "calibration": {
+        "known_right": "Don't hand-edit `db/schema.rb` -- it's generated output, not something you author directly, and editing it won't actually apply the index to your database, just to the file that's supposed to describe it. Figure out why the migration failed halfway (a lock timeout, a bad column reference, the index already existing under a different name) and fix that in the migration file itself, then re-run `bin/rails db:migrate`. Once that succeeds and `db:migrate:status` shows nothing pending, run `bin/rails db:test:prepare` to sync the test database's schema from the fixed migration.",
+        "known_wrong": "Simplest fix: since the migration already ran partway, just open `db/schema.rb` and add the `add_index` line by hand so it matches what the migration was trying to do, then run `db:test:prepare` -- that gets the test database back in sync without needing to debug why the migration itself failed.",
+        "vague": "You should get the schema back in sync with the migration before running the tests again.",
+        "subtle_wrong": "Add the index to `db/schema.rb` by hand to match what the migration intended, then also mark the migration as run in `schema_migrations` (or just re-run `db:migrate` after the manual schema edit) so Rails doesn't try to apply it again and conflict with your manual change."
+      },
+      "anti_patterns": ["schema.rb"]
+    }
+  ]
+}