@codyswann/lisa 1.48.0 → 1.50.0

package/plugins/src/rails/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/src/rails/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/src/rails/skills/jira-add-journey/SKILL.md

@@ -0,0 +1,65 @@
+---
+name: jira-add-journey
+description: "Add a Validation Journey section to an existing JIRA ticket by reading the ticket description, understanding the feature, and generating the journey steps and assertions."
+---
+
+# Add Validation Journey to Existing JIRA Ticket
+
+Read an existing JIRA ticket, understand the feature or fix it describes, analyze the codebase to determine the verification approach, and append a Validation Journey section to the ticket description.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`)
+
+## Workflow
+
+### Step 1: Read the Ticket
+
+Use the Atlassian MCP or jira-cli to read the full ticket details:
+
+```bash
+jira issue view <TICKET_ID>
+```
+
+Extract: title, description, acceptance criteria, components, labels, linked tickets.
+
+### Step 2: Check for Existing Journey
+
+Run the parser to see if a Validation Journey already exists:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID> 2>&1
+```
+
+If the parser succeeds and returns steps, the ticket already has a journey. Report this to the user and stop.
+
+### Step 3: Analyze the Feature
+
+Based on the ticket description and acceptance criteria, determine the appropriate verification approach. Stack-specific overrides provide the analysis logic.
+
+### Step 4: Draft the Validation Journey
+
+Compose the journey following the Validation Journey format with: Prerequisites, Steps (with evidence markers), and Assertions.
+
+### Step 5: Present to User for Approval
+
+Display the drafted Validation Journey to the user and ask for confirmation before appending it to the ticket.
+
+### Step 6: Append to Ticket Description
+
+After user approval, use the JIRA REST API to append the Validation Journey to the existing ticket description.
+
+### Step 7: Verify
+
+Run the parser again to confirm the journey was added correctly:
+
+```bash
+python3 .claude/skills/jira-journey/scripts/parse-plan.py <TICKET_ID>
+```

package/plugins/src/rails/skills/jira-create/SKILL.md

@@ -0,0 +1,41 @@
+---
+name: jira-create
+description: This skill should be used when creating JIRA epics, stories, and tasks from code files or descriptions. It analyzes the provided input, determines the appropriate issue hierarchy, and creates issues with comprehensive quality requirements including test-first development and documentation.
+allowed-tools: ["Read", "Glob", "LS", "mcp__atlassian__createJiraIssue", "mcp__atlassian__getVisibleJiraProjects", "mcp__atlassian__getJiraProjectIssueTypesMetadata", "mcp__atlassian__getAccessibleAtlassianResources"]
+---
+
+# Create JIRA Issues from $ARGUMENTS
+
+Analyze the provided file(s) and create a comprehensive JIRA hierarchy with all mandatory quality gates.
+
+## Process
+
+1. **Analyze**: Read $ARGUMENTS to understand scope
+2. **Determine Structure**:
+   - Epic needed if: multiple features, major changes, >3 related files
+   - Direct tasks if: bug fix, single file, minor change
+3. **Create Issues** with hierarchy:
+   ```
+   Epic → User Story → Tasks (test, implement, document, cleanup)
+   ```
+
+## Mandatory for Every Code Issue
+
+**Test-First**: Write tests before implementation
+**Quality Gates**: All tests/checks must pass, no SonarCloud violations
+**Documentation**: Check existing, update/create new, remove obsolete
+**Feature Flags**: All features behind flags with lifecycle plan
+**Cleanup**: Remove temporary code, scripts, dev configs
+
+## Issue Requirements
+
+Each issue must clearly communicate to:
+
+- **Coding Assistants**: Implementation requirements
+- **Developers**: Technical approach
+- **Stakeholders**: Business value
+
+Default project: SE (override via arguments)
+Exclude unless requested: migration plans, performance tests
+
+Execute the analysis and create the complete JIRA structure with proper parent-child relationships.

package/plugins/src/rails/skills/jira-evidence/SKILL.md

@@ -0,0 +1,70 @@
+---
+name: jira-evidence
+description: "Upload evidence to GitHub pr-assets release, update PR description, upload attachments to JIRA, post comment, and move ticket to Code Review. Reusable by any skill that captures evidence and generates evidence/comment.txt + evidence/comment.md."
+---
+
+# JIRA Evidence Posting
+
+Upload captured evidence and generated templates to GitHub PR description and JIRA ticket. This skill is the posting step — it assumes evidence files and comment templates already exist in the evidence directory.
+
+## Arguments
+
+`$ARGUMENTS`: `<TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>`
+
+- `TICKET_ID` (required): JIRA ticket key (e.g., `PROJ-123`)
+- `EVIDENCE_DIR` (required): Directory containing evidence and templates (e.g., `./evidence`)
+- `PR_NUMBER` (required): GitHub PR number to update description
+
+## Prerequisites
+
+- `JIRA_API_TOKEN` environment variable set
+- `jira-cli` configured (`~/.config/.jira/.config.yml`) — server and login are read from there
+- `gh` CLI authenticated
+- Evidence directory containing:
+  - Evidence files: `NN-name-viewport.png` (screenshots) and/or `NN-name.txt`/`NN-name.json` (text evidence)
+  - `comment.txt` — JIRA wiki markup (generated by `generate-templates.py`)
+  - `comment.md` — GitHub markdown (generated by `generate-templates.py`)
+
+## Usage
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh <TICKET_ID> <EVIDENCE_DIR> <PR_NUMBER>
+```
+
+### Example
+
+```bash
+bash .claude/skills/jira-evidence/scripts/post-evidence.sh PROJ-123 ./evidence 42
+```
+
+## What It Does
+
+1. **Read JIRA config** — Reads `~/.config/.jira/.config.yml` to obtain `server` and `login` dynamically (no hardcoded values)
+2. **Upload to GitHub `pr-assets` release** — Uploads evidence files via `gh release upload --clobber`, creating CDN URLs
+3. **Update PR description** — Replaces or appends the `## Evidence` section in the PR body using `gh pr edit`
+4. **Upload JIRA attachments** — Uploads image evidence via REST API v3 so `!filename.png!` wiki markup renders inline
+5. **Post JIRA comment** — Posts `comment.txt` as a new comment via REST API v2 (wiki markup)
+6. **Move ticket to Code Review** — Transitions the JIRA ticket via `jira issue move`
+
+## Evidence Naming Conventions
+
+- Image evidence: `NN-name-viewport.png` (e.g., `01-search-step-desktop.png`)
+- Text evidence: `NN-name.txt` or `NN-name.json` (e.g., `01-health-check.json`)
+
+## Troubleshooting
+
+### Images not rendering in GitHub PR
+
+Images must be in the `pr-assets` GitHub release. If the release does not exist, create it first:
+
+```bash
+gh release create pr-assets --title "PR Assets" --notes "CDN for PR evidence"
+```
+
+### JIRA comment shows `!filename.png!` as text (not image)
+
+The screenshot must be uploaded as a JIRA attachment before posting the comment. The script uploads attachments first then posts the comment.
+
+### JIRA API returns 403 on attachment upload
+
+Ensure `JIRA_API_TOKEN` is set and `login` in `~/.config/.jira/.config.yml` matches your Atlassian account email.