@codyswann/lisa 2.121.1 → 2.123.0

package/plugins/lisa-rails-agy/skills/action-view-best-practices/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: action-view-best-practices
+description: Build or Refactor Rails views, partials, and templates into clean, maintainable code. Use when views have inline Ruby logic, deeply nested partials, jQuery or legacy JavaScript, helper methods returning HTML, or when the user asks to modernize, refactor, or clean up Rails views. Applies patterns - Turbo Frames, Turbo Streams, Stimulus controllers, ViewComponent, presenters, strict locals, and proper partial extraction.
+---
+
+# Rails View Refactoring
+
+Views should contain markup and minimal display logic. If a view has conditionals, calculations, query calls, or complex Ruby blocks, it needs refactoring. The modern Rails 8+ stack uses Hotwire (Turbo + Stimulus) for interactivity, Propshaft for assets, and Importmap for JavaScript — no build step required.
+
+## Decision Framework
+
+Read the view and classify each block of code:
+
+| Code type                                               | Extract to                      | Location                                   |
+| ------------------------------------------------------- | ------------------------------- | ------------------------------------------ |
+| Reusable UI patterns (buttons, cards, modals, badges)   | ViewComponent                   | `app/components/`                          |
+| Display logic (formatting, conditional CSS, label text) | Presenter or ViewComponent      | `app/presenters/` or `app/components/`     |
+| HTML-returning helper methods                           | ViewComponent                   | `app/components/`                          |
+| Inline `<script>` tags and jQuery                       | Stimulus controller             | `app/javascript/controllers/`              |
+| AJAX calls, remote forms, `$.ajax`                      | Turbo Frame or Turbo Stream     | ERB template + controller response         |
+| Partial page updates via JavaScript                     | Turbo Frame                     | Wrap in `turbo_frame_tag`                  |
+| Real-time broadcasts (chat, notifications)              | Turbo Stream                    | Model `broadcasts_to` or controller stream |
+| One-off page sections that are too long                 | Partial with strict locals      | `app/views/shared/` or alongside view      |
+| Complex data assembly for the view                      | Presenter                       | `app/presenters/`                          |
+| Repeated inline Ruby (loops with logic)                 | Collection partial or component | Partial or component                       |
+| Instance variables used across partials                 | Locals / strict locals          | Pass explicitly                            |
+
+## Modernizing to Hotwire
+
+### Replace jQuery AJAX with Turbo Frames
+
+Turbo Frames update a specific section of the page without a full reload. No JavaScript needed.
+
+```erb
+<%# Before — jQuery AJAX %>
+<div id="player-stats"></div>
+<script>
+  $.get('/players/<%= @player.id %>/stats', function(data) {
+    $('#player-stats').html(data);
+  });
+</script>
+
+<%# After — Turbo Frame %>
+<%= turbo_frame_tag "player_stats" do %>
+  <%= render partial: "players/stats", locals: { player: @player } %>
+<% end %>
+```
+
+The linked page just needs a matching `turbo_frame_tag` with the same ID and Turbo handles the rest.
+
+### Replace Remote Forms with Turbo
+
+Rails UJS `remote: true` forms are deprecated. Turbo handles forms natively.
+
+```erb
+<%# Before — Rails UJS %>
+<%= form_with model: @player, remote: true do |f| %>
+  ...
+<% end %>
+
+<%# After — Turbo (just remove remote: true, Turbo handles it) %>
+<%= form_with model: @player do |f| %>
+  ...
+<% end %>
+```
+
+Turbo intercepts all form submissions by default. For partial updates, wrap the form in a `turbo_frame_tag`. For multi-target updates, respond with a Turbo Stream:
+
+```erb
+<%# app/views/players/update.turbo_stream.erb %>
+<%= turbo_stream.replace "player_header" do %>
+  <%= render partial: "players/header", locals: { player: @player } %>
+<% end %>
+
+<%= turbo_stream.update "flash_messages" do %>
+  <%= render partial: "shared/flash" %>
+<% end %>
+```
+
+### Replace Inline JavaScript with Stimulus
+
+Any behavior attached to DOM elements (toggles, dropdowns, form validation, clipboard, modals) should be a Stimulus controller.
+
+```erb
+<%# Before — inline JS / jQuery %>
+<button onclick="document.getElementById('details').classList.toggle('hidden')">
+  Toggle
+</button>
+<div id="details" class="hidden">...</div>
+
+<%# After — Stimulus %>
+<div data-controller="toggle">
+  <button data-action="click->toggle#switch">Toggle</button>
+  <div data-toggle-target="content" class="hidden">...</div>
+</div>
+```
+
+```javascript
+// app/javascript/controllers/toggle_controller.js
+import { Controller } from "@hotwired/stimulus";
+
+export default class extends Controller {
+  static targets = ["content"];
+
+  switch() {
+    this.contentTarget.classList.toggle("hidden");
+  }
+}
+```
+
+Conventions:
+
+- One behavior per controller — keep them small and composable
+- Name controllers after what they do: `toggle`, `clipboard`, `dropdown`, `search-form`
+- Use `targets` for elements, `values` for data, `classes` for CSS class names
+- Never manipulate DOM outside the controller's element scope
+
+### Replace Polling with Turbo Streams
+
+For real-time updates, use Turbo Streams over WebSockets instead of JavaScript polling.
+
+```ruby
+# app/models/score.rb
+class Score < ApplicationRecord
+  broadcasts_to ->(score) { [score.game] }, inserts_by: :prepend
+end
+```
+
+```erb
+<%# Subscribe in the view %>
+<%= turbo_stream_from @game %>
+
+<div id="scores">
+  <%= render @game.scores %>
+</div>
+```
+
+New scores automatically appear without any JavaScript.
+
+## View Component Patterns
+
+### When to Use ViewComponent vs Partials
+
+Use **partials** for:
+
+- One-off page sections that won't be reused
+- Simple markup extraction to reduce file length
+- Layouts and structural wrappers
+
+Use **ViewComponent** for:
+
+- Reusable UI elements (buttons, cards, badges, modals, alerts)
+- Components with display logic or multiple variants
+- Anything you'd want to unit test in isolation
+- Complex components with slots for flexible content injection
+
+### ViewComponent Example
+
+```ruby
+# app/components/stat_card_component.rb
+class StatCardComponent < ViewComponent::Base
+  def initialize(label:, value:, trend: nil)
+    @label = label
+    @value = value
+    @trend = trend
+  end
+
+  def trend_class
+    case @trend
+    when :up then "text-green-600"
+    when :down then "text-red-600"
+    else "text-gray-500"
+    end
+  end
+end
+```
+
+```erb
+<%# app/components/stat_card_component.html.erb %>
+<div class="rounded-lg border p-4">
+  <dt class="text-sm text-gray-500"><%= @label %></dt>
+  <dd class="text-2xl font-semibold"><%= @value %></dd>
+  <% if @trend %>
+    <span class="<%= trend_class %>"><%= @trend == :up ? "↑" : "↓" %></span>
+  <% end %>
+</div>
+```
+
+```erb
+<%# Usage %>
+<%= render StatCardComponent.new(label: "Batting Avg", value: ".312", trend: :up) %>
+```
+
+## Partial Best Practices
+
+### Use Strict Locals
+
+Always declare expected locals at the top of partials. This was added in Rails 7.1 and prevents silent nil bugs.
+
+```erb
+<%# app/views/players/_card.html.erb %>
+<%# locals: (player:, show_stats: false) %>
+
+<div class="player-card">
+  <h3><%= player.name %></h3>
+  <% if show_stats %>
+    <%= render partial: "players/stats", locals: { player: player } %>
+  <% end %>
+</div>
+```
+
+### Use Collection Rendering
+
+Never loop and render partials manually.
+
+```erb
+<%# Before — slow, verbose %>
+<% @players.each do |player| %>
+  <%= render partial: "players/card", locals: { player: player } %>
+<% end %>
+
+<%# After — collection rendering (faster, cleaner) %>
+<%= render partial: "players/card", collection: @players, as: :player %>
+```
+
+### Avoid Deeply Nested Partials
+
+If partial A renders partial B which renders partial C, it's too deep. Flatten the structure or extract to a ViewComponent that composes its own sub-components.
+
+## Presenters for Complex View Logic
+
+When a view needs data from multiple sources or complex formatting, use a presenter instead of cramming logic into the template.
+
+```ruby
+# app/presenters/player_profile_presenter.rb
+class PlayerProfilePresenter
+  def initialize(player, current_user)
+    @player = player
+    @current_user = current_user
+  end
+
+  def display_name
+    "#{@player.first_name} #{@player.last_name}"
+  end
+
+  def contract_status_badge
+    if @player.free_agent?
+      { text: "Free Agent", color: "green" }
+    elsif @player.contract_years_remaining <= 1
+      { text: "Expiring", color: "yellow" }
+    else
+      { text: "Under Contract", color: "gray" }
+    end
+  end
+
+  def can_edit?
+    @current_user.admin? || @current_user.team == @player.team
+  end
+
+  def formatted_salary
+    ActiveSupport::NumberHelper.number_to_currency(@player.salary)
+  end
+end
+```
+
+```erb
+<%# Clean view %>
+<h1><%= @presenter.display_name %></h1>
+
+<% badge = @presenter.contract_status_badge %>
+<%= render BadgeComponent.new(text: badge[:text], color: badge[:color]) %>
+
+<%= @presenter.formatted_salary %>
+
+<% if @presenter.can_edit? %>
+  <%= link_to "Edit", edit_player_path(@player) %>
+<% end %>
+```
+
+## Eliminating Helper Abuse
+
+Rails helpers that return HTML are hard to test, hard to read, and hard to compose. Move them to ViewComponents.
+
+```ruby
+# Before — helper returning HTML (bad)
+module PlayersHelper
+  def player_avatar(player, size: :md)
+    sizes = { sm: "w-8 h-8", md: "w-12 h-12", lg: "w-16 h-16" }
+    if player.avatar.attached?
+      image_tag player.avatar, class: "rounded-full #{sizes[size]}"
+    else
+      content_tag :div, player.initials,
+        class: "rounded-full #{sizes[size]} bg-gray-300 flex items-center justify-center"
+    end
+  end
+end
+
+# After — ViewComponent (good)
+# app/components/avatar_component.rb
+class AvatarComponent < ViewComponent::Base
+  SIZES = { sm: "w-8 h-8", md: "w-12 h-12", lg: "w-16 h-16" }.freeze
+
+  def initialize(player:, size: :md)
+    @player = player
+    @size = size
+  end
+  # ... with its own template and tests
+end
+```
+
+Keep helpers for non-HTML formatting utilities only (number formatting, date formatting, text truncation).
+
+## Refactoring Process
+
+1. **Audit the view layer** — identify inline Ruby logic, jQuery, `remote: true` forms, helpers returning HTML, and deeply nested partials.
+2. **Remove jQuery and inline JS first** — replace with Stimulus controllers. This is the highest-impact change.
+3. **Replace `remote: true` and AJAX** — Turbo handles forms and links natively. Convert to Turbo Frames and Turbo Streams.
+4. **Add strict locals** to all existing partials.
+5. **Extract reusable UI patterns** into ViewComponents.
+6. **Move display logic** from views into presenters or component classes.
+7. **Move HTML-returning helpers** into components.
+8. **Flatten nested partials** — if nesting is deeper than 2 levels, restructure.
+9. **Add collection rendering** wherever loops render partials.
+10. **Remove all instance variables from partials** — pass data via locals only.
+
+## What NOT to Do
+
+- Don't put query calls in views — ever. Not even `count` or `any?`. Use the presenter or controller.
+- Don't use `content_for` for complex logic — it creates invisible dependencies between layouts and views.
+- Don't create Stimulus controllers that replicate what Turbo Frames already handle.
+- Don't mix jQuery and Stimulus in the same app — commit to full migration.
+- Don't render entire pages as ViewComponents — they are for reusable pieces, not whole pages.
+- Don't use `html_safe` or `raw` unless you are certain the content is sanitized.
+- Don't pass more than 3-4 locals to a partial — if you need more, it should be a component or presenter.
+- Don't use `render partial:` inside loops — use collection rendering instead.

package/plugins/lisa-rails-agy/skills/active-record-model-best-practices/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: active-record-model-best-practices
+description: Best practices for Ruby on Rails models, splitting code into well-organized, maintainable code. Use when a model exceeds ~100 lines, has mixed responsibilities, or when the user asks to refactor, extract, clean up, or organize a Rails model. Applies patterns: concerns, service objects, query objects, form objects, and value objects.
+---
+
+# Rails Model Refactoring
+
+When refactoring a Rails model, analyze the file and extract code into the appropriate pattern based on what the code does. The model itself should only contain associations, enums, basic validations, and concern includes.
+
+## Decision Framework
+
+Read the model file and classify each block of code:
+
+| Code type | Extract to | Location |
+|---|---|---|
+| Related scopes + simple methods sharing a theme | Concern | `app/models/concerns/` |
+| Business logic, multi-step operations, callbacks with side effects | Service object | `app/services/` |
+| Complex queries, multi-join scopes, reporting queries | Query object | `app/queries/` |
+| Context-specific validations (e.g. registration vs admin update) | Form object | `app/forms/` |
+| Domain concepts beyond a primitive (money, coordinates, scores) | Value object | `app/models/` |
+| Associations, enums, core validations, simple scopes | Keep on model | — |
+
+## Patterns
+
+### Concerns
+
+Use for grouping related scopes, validations, callbacks, and simple instance methods that share a single theme. Name the concern after the capability it provides.
+
+```ruby
+# app/models/concerns/searchable.rb
+module Searchable
+  extend ActiveSupport::Concern
+
+  included do
+    scope :search, ->(query) { where("name ILIKE ?", "%#{query}%") }
+  end
+
+  def matching_terms(query)
+    name.scan(/#{Regexp.escape(query)}/i)
+  end
+end
+```
+
+### Service Objects
+
+Use for business logic, orchestration of multiple models, and anything triggered by a user action that involves more than a simple CRUD operation. Follow the single-responsibility principle — one service, one operation.
+
+```ruby
+# app/services/players/calculate_stats.rb
+module Players
+  class CalculateStats
+    def initialize(player)
+      @player = player
+    end
+
+    def call
+      # complex logic here
+    end
+  end
+end
+```
+
+Conventions:
+- Namespace under the model name: `Players::CalculateStats`
+- Single public method: `call`
+- Accept dependencies via `initialize`
+- Return a result or raise a domain-specific error
+
+### Query Objects
+
+Use for complex database queries that involve joins, subqueries, CTEs, or multi-condition filtering that would clutter a model with scopes.
+
+```ruby
+# app/queries/players/free_agent_query.rb
+module Players
+  class FreeAgentQuery
+    def initialize(relation = Player.all)
+      @relation = relation
+    end
+
+    def call(filters = {})
+      @relation
+        .where(contract_status: :expired)
+        .where("age < ?", filters[:max_age])
+        .joins(:stats)
+        .order(war: :desc)
+    end
+  end
+end
+```
+
+Conventions:
+- Accept a base relation in `initialize` (default to `Model.all`)
+- Return an ActiveRecord relation so it remains chainable
+- Single public method: `call`
+
+### Form Objects
+
+Use when validations only apply in specific contexts, or when a form spans multiple models.
+
+```ruby
+# app/forms/player_registration_form.rb
+class PlayerRegistrationForm
+  include ActiveModel::Model
+  include ActiveModel::Attributes
+
+  attribute :name, :string
+  attribute :email, :string
+  attribute :team_id, :integer
+  attribute :position, :string
+
+  validates :name, :email, :position, presence: true
+  validates :email, format: { with: URI::MailTo::EMAIL_REGEXP }
+
+  def save
+    return false unless valid?
+    Player.create!(attributes)
+  end
+end
+```
+
+### Value Objects
+
+Use for domain concepts that deserve their own identity beyond a raw primitive.
+
+```ruby
+# app/models/batting_average.rb
+class BattingAverage
+  include Comparable
+
+  def initialize(hits, at_bats)
+    @hits = hits
+    @at_bats = at_bats
+  end
+
+  def value
+    return 0.0 if @at_bats.zero?
+    (@hits.to_f / @at_bats).round(3)
+  end
+
+  def elite?
+    value >= 0.300
+  end
+
+  def <=>(other)
+    value <=> other.value
+  end
+end
+```
+
+## Refactoring Process
+
+1. **Read the entire model** and identify every method, scope, callback, and validation.
+2. **Classify each block** using the decision framework table above.
+3. **Extract in order**: value objects first, then query objects, then service objects, then concerns. Do concerns last because some may become unnecessary after other extractions.
+4. **Update the model** to include concerns and delegate to new objects.
+5. **Verify** that the slimmed-down model only contains: associations, enums, core validations, and concern includes.
+6. **Create or update tests** for each extracted class. Each new class gets its own spec file mirroring the source path.
+
+## What NOT to Do
+
+- Don't extract everything — simple one-line scopes and basic validations belong on the model.
+- Don't create a class for trivial logic just to hit a line count target.
+- Don't use concerns as junk drawers — each concern should have a clear, single theme.
+- Don't break ActiveRecord conventions (e.g. don't move associations into concerns).
+- Don't introduce callback-heavy service objects — prefer explicit invocation over implicit hooks.

package/plugins/lisa-rails-agy/skills/e2e-coverage-gaps/SKILL.md

@@ -0,0 +1,105 @@
+---
+name: e2e-coverage-gaps
+description: Playwright/e2e coverage-gap explorer that FEEDS THE LIFECYCLE. Use when asked to find paths the automated end-to-end suite does NOT cover — routes with no test at all, or flows that are only happy-path tested (missing error, validation, permission, empty, loading, and edge states). It inventories the app's routes and the existing Playwright tests, explores the running app to confirm each uncovered or under-covered path is real and reachable, and files one build-ready missing-test ticket per gap via lisa:tracker-write. For human usability/experience issues (confusing, cramped, or broken UI), use the exploratory-qa skill instead.
+---
+
+# E2E Coverage Gaps
+
+## Overview
+
+Find where the automated end-to-end (Playwright) suite is **blind**: routes with no test at all, and
+flows that only assert the **happy path** while ignoring error, permission, empty, loading, and edge
+cases. Inventory the app's routes and the existing tests, explore the running app to confirm each gap
+is real and reachable, then file each gap as a **build-ready missing-test work item** so it enters the
+Lisa lifecycle.
+
+This skill is purely about **automated-coverage gaps**. It does not judge whether the UI is confusing
+or pretty — for human usability findings, use the `exploratory-qa` skill.
+
+## Parameters
+
+- **`target-url | env`** (first positional) — the app to inventory and explore.
+- **`ready=true|false`** — build-ready state for the missing-test tickets (**default `true`**). Adding
+  missing coverage is safe to queue, so these default to build-ready; pass `ready=false` to leave them
+  in the backlog for human triage.
+
+## Core Workflow
+
+### 1. Establish Scope
+
+- Identify the target environment, account type, and browser requirement, and read the `ready` flag
+  (default `true`).
+- **Confirm the tracker is configured.** Gaps are filed as tickets, so read `tracker` from
+  `.lisa.config.json` (local overrides global). If it is unset, stop and report that the tracker must
+  be configured (via `/lisa:setup:jira` / `:github` / `:linear`) before gaps can be filed.
+
+### 2. Inventory App Routes
+
+- Enumerate every route/screen from the project's routing source — filesystem routes, the router
+  config, navigation definitions, or a generated sitemap.
+- For each route capture: its path + params, the auth/role it requires, and the primary user actions
+  reachable from it (forms, mutations, filters, flows).
+
+### 3. Inventory Existing Playwright Coverage
+
+- Inspect the Playwright config, auth/setup projects, fixtures, constants, selectors, spec directories,
+  skipped/TODO/flaky tests, retries, and viewport/device projects.
+- For each spec, record which route(s)/flow(s) it exercises and whether it asserts **behavior** or just
+  **presence**.
+- Use existing test helpers/selectors when exploring — they reveal intended flows and stable hooks.
+
+### 4. Compute the Gap Matrix
+
+Map routes/flows against existing coverage and classify each gap:
+
+- **Uncovered route/flow:** no test touches it at all.
+- **Happy-path-only:** the success case is tested but the non-happy paths are not — missing
+  error/validation, permission/denied, empty/zero-state, loading/slow, and boundary/edge scenarios.
+- **Assertion-thin:** a test exists but asserts presence rather than behavior/outcome.
+- **Skipped/TODO/flaky:** coverage exists but is disabled or unreliable.
+- **Breakpoint gap:** a flow is only tested at a single viewport when behavior changes across
+  breakpoints.
+
+### 5. Explore to Confirm
+
+- Navigate each candidate gap in the running app to confirm it is real, reachable, and worth a test.
+  Discard gaps that aren't actually reachable or are intentionally out of scope.
+
+### 6. File One Ticket Per Gap
+
+Each confirmed gap becomes a leaf **missing-test** work item created via `lisa:tracker-write` (the
+vendor-neutral writer — it dispatches to the configured tracker and runs the validation gate; never
+call a vendor `*-write-*` skill directly), `issue_type: Task`, **build-ready per the `ready` flag
+(default `true`)**. Pass `build_ready` explicitly on every create. Each ticket MUST specify:
+
+- The **route/flow** and the exact **user behavior the test must assert**.
+- **Which scenario is missing** (uncovered vs which non-happy path: error / validation / permission /
+  empty / loading / edge / breakpoint).
+- The **stable selector / fixture / flow** to use — concrete and automatable.
+- **Three-audience description** + **Gherkin acceptance criteria** describing the test to add.
+
+### Idempotency — don't spam duplicates
+
+Before creating a ticket, search the tracker for an **open** ticket carrying a stable marker
+`[lisa-e2e-coverage-gaps] <gap-key>` in its body (the `<gap-key>` is a stable slug of route + missing
+scenario, e.g. `checkout/payment-declined` or `dashboard/empty-state@mobile`). If one exists, reference
+it instead of duplicating. **Match by the marker, never by title.** A *closed* prior ticket does not
+suppress a genuine new gap.
+
+## Output
+
+No report file. Emit a concise in-session summary:
+
+- **Route inventory:** count of routes/screens discovered.
+- **Existing coverage:** strengths and thin areas (skipped/flaky, assertion-thin, single-viewport).
+- **Gap matrix:** uncovered vs happy-path-only vs breakpoint gaps.
+- **Tickets filed:** each gap with its created/referenced ticket ref and build-ready state.
+
+## Quality Bar
+
+- Distinguish **no coverage** from **happy-path-only** — both are gaps, but the ticket must say which.
+- Every ticket must stand alone for an implementer who was not in the session and must be concretely
+  automatable (named route, behavior, and stable hook).
+- Do not refile gaps already covered or already ticketed (marker check).
+- This skill is about automated coverage only — route human usability issues to `exploratory-qa`.
+- Preserve unrelated repo changes.