ariadna 1.3.0 → 2.0.0

data/data/skills/rails-frontend/SKILL.md

@@ -0,0 +1,187 @@
+---
+name: rails-frontend
+description: Ruby on Rails frontend conventions — Hotwire, Turbo, Stimulus, views, components, assets. Use when implementing frontend features, building views, or working with JavaScript/CSS.
+---
+
+# Rails Frontend
+
+Core conventions for Rails frontend work using the Hotwire stack: Turbo Drive, Turbo Frames, Turbo Streams, and Stimulus controllers.
+
+## Sub-files
+
+- [VIEWS.md](VIEWS.md) — ERB conventions, layouts, partials, Turbo Frame wrapping
+- [COMPONENTS.md](COMPONENTS.md) — Stimulus controllers, presenter pattern, component composition
+- [ASSETS.md](ASSETS.md) — CSS architecture, design tokens, asset pipeline
+
+---
+
+## Stack
+
+- **Turbo Drive** — replaces full page loads with fetch + DOM swap
+- **Turbo Frames** — scope navigation to a region; swap on response
+- **Turbo Streams** — targeted DOM mutations via `<turbo-stream>` elements
+- **Stimulus** — lightweight JS controllers bound to DOM elements
+- **No React/Vue** — Hotwire is the default; reach for Stimulus before any SPA framework
+
+---
+
+## Turbo Essentials
+
+### HTTP Status Codes
+
+Always use these — Turbo depends on them:
+
+| Status | Meaning | When to Use |
+|--------|---------|-------------|
+| `303 See Other` | Redirect after success | After any create/update/destroy |
+| `422 Unprocessable Entity` | Validation failure | Re-render form in frame |
+| Never `200` | For redirect-expecting forms | — |
+
+```ruby
+def create
+  if @card.save
+    redirect_to @card, status: :see_other
+  else
+    render :new, status: :unprocessable_entity
+  end
+end
+```
+
+### Turbo Frames
+
+Scope to the **smallest rerenderable unit**. Always use `dom_id` for IDs:
+
+```erb
+<turbo-frame id="<%= dom_id(card) %>">
+  <%= render "cards/card", card: card %>
+</turbo-frame>
+```
+
+Lazy loading with placeholder:
+
+```erb
+<turbo-frame id="activity_feed" src="<%= activity_feed_path %>" loading="lazy">
+  <p>Loading...</p>
+</turbo-frame>
+```
+
+Style the loading state with the auto-added `[busy]` attribute:
+
+```css
+turbo-frame[busy] { opacity: 0.5; pointer-events: none; }
+```
+
+### Turbo Streams
+
+Prefer the 8 built-in actions: `append`, `prepend`, `replace`, `update`, `remove`, `before`, `after`, `refresh`.
+
+Broadcast from model callbacks:
+
+```ruby
+class Card < ApplicationRecord
+  after_create_commit  -> { broadcast_append_to board, target: "cards" }
+  after_update_commit  -> { broadcast_replace_to board }
+  after_destroy_commit -> { broadcast_remove_to board }
+end
+```
+
+Custom stream actions register on `StreamActions`; `this` is the `<turbo-stream>` element:
+
+```javascript
+import { StreamActions } from "@hotwired/turbo"
+
+StreamActions.flash = function () {
+  const flash = document.createElement("div")
+  flash.className = `flash flash--${this.getAttribute("type") || "notice"}`
+  flash.textContent = this.getAttribute("message")
+  document.getElementById("flash_container").appendChild(flash)
+}
+```
+
+### Turbo Drive Events
+
+| Event | Use For |
+|-------|---------|
+| `turbo:before-cache` | Clean transient UI (close dropdowns, remove flashes) |
+| `turbo:before-render` | Page transition animations — **pausable** via `preventDefault()` + `detail.resume()` |
+| `turbo:load` | Post-navigation setup (equivalent to `DOMContentLoaded`) |
+| `turbo:frame-load` | Frame navigation complete — update active states here, NOT on `turbo:click` |
+
+Always guard animations against `data-turbo-preview` (cached snapshot renders):
+
+```javascript
+document.addEventListener("turbo:before-render", (event) => {
+  if (document.documentElement.hasAttribute("data-turbo-preview")) return
+  event.preventDefault()
+  document.documentElement.classList.add("page-leaving")
+  document.documentElement.addEventListener("animationend", () => event.detail.resume(), { once: true })
+})
+```
+
+### Optimistic UI
+
+1. Store markup in a `<template>` containing a `<turbo-stream>` (prevents premature execution)
+2. On `turbo:submit-start`, clone and append to the DOM
+3. Server responds with `turbo_stream.refresh` to reconcile
+
+Use client-side ULIDs for optimistic IDs (time-ordered, collision-resistant):
+
+```javascript
+function generateULID() {
+  const time = Date.now().toString(36).padStart(10, "0")
+  const rand = Array.from(crypto.getRandomValues(new Uint8Array(10)))
+    .map((b) => b.toString(36).padStart(2, "0")).join("").slice(0, 16)
+  return (time + rand).toUpperCase()
+}
+```
+
+---
+
+## Presenter Pattern
+
+Use plain Ruby presenter classes in `app/models/` (not a separate `app/presenters/` directory) to keep view logic out of ERB templates.
+
+**Create a presenter when:** a view needs 3+ conditionals, multiple computed values, HTML generation, or fragment caching.
+
+Key anatomy:
+
+```ruby
+class User::Filtering
+  def initialize(user, filter, expanded: false)
+    @user, @filter, @expanded = user, filter, expanded
+  end
+
+  def boards = @boards ||= user.boards.ordered_by_recently_accessed  # memoized
+  def show_tags? = filter.tags.any?                                   # boolean for display
+  def cache_key                                                        # for fragment caching
+    ActiveSupport::Cache.expand_cache_key([user, filter, boards], "user-filtering")
+  end
+end
+```
+
+- **Domain-organized names**: `User::Filtering`, not `FilteringPresenter`
+- **Include ActionView helpers** when generating HTML: `include ActionView::Helpers::TagHelper`
+- **Factory methods** on models: `event.description_for(user)` for discoverable APIs
+- **Controller concerns** for cross-controller instantiation
+
+---
+
+## View Transitions API
+
+Enable in the layout:
+
+```erb
+<meta name="view-transition" content="same-origin">
+```
+
+Direction-aware transitions: capture in `turbo:click`, apply in `turbo:before-render`, clean up in `turbo:load`.
+
+---
+
+## Key Rules
+
+- No query calls (`where`, `find`, `count`) in ERB — push to presenters or controllers
+- No conditionals deeper than one level in templates
+- Always pass locals explicitly to partials — never rely on instance variables inside partials
+- Use `dom_id` for all Turbo Frame and Stream target IDs
+- Clean transient UI on `turbo:before-cache` (dropdowns, flash messages, open modals)

data/data/skills/rails-frontend/VIEWS.md

@@ -0,0 +1,168 @@
+# Views — ERB, Layouts, Partials
+
+Templates are rendering surfaces, not logic containers. Delegate decisions to presenters or model methods.
+
+## ERB Conventions
+
+**Rules:**
+- No conditionals deeper than one level
+- No query calls (`where`, `find`, `count`) — use presenters
+- Use `content_for` to inject section-specific content into layouts
+- Prefer `tag.div` helpers inside presenters over inline ERB for complex HTML
+
+```erb
+<%# Bad — logic in template %>
+<% if user.avatar.attached? && user.avatar.variable? %>
+  <%= image_tag user.avatar.variant(resize_to_limit: [100, 100]) %>
+<% else %>
+  <%= image_tag "default_avatar.png" %>
+<% end %>
+
+<%# Good — delegate to presenter %>
+<%= presenter.avatar_tag %>
+```
+
+### `content_for` Pattern
+
+```erb
+<%# app/views/messages/show.html.erb %>
+<% content_for :title, @message.subject %>
+<% content_for :head do %>
+  <%= javascript_include_tag "trix" %>
+<% end %>
+```
+
+```erb
+<%# app/views/layouts/application.html.erb %>
+<title><%= content_for(:title) || "App" %></title>
+<%= yield :head %>
+```
+
+---
+
+## Partials
+
+**Extract when:** the same markup appears in 2+ templates, or a clear UI component boundary exists.
+
+**Naming:**
+- Leading underscore: `_card.html.erb`
+- Named after the UI concept, not the model: `_card.html.erb` not `_message_display.html.erb`
+- Cross-controller partials in `app/views/shared/`
+
+**Always pass explicit locals — never rely on instance variables inside partials:**
+
+```erb
+<%# Good %>
+<%= render partial: "messages/card", locals: { message: message, show_actions: true } %>
+
+<%# Good — short form for collections %>
+<%= render partial: "messages/message", collection: @messages, as: :message %>
+
+<%# Bad — implicit instance variable dependency %>
+<%= render partial: "messages/card" %>
+```
+
+---
+
+## Turbo Frame Wrapping
+
+Wrap the **smallest rerenderable unit**. Frame IDs must match between the source page and the server response.
+
+```erb
+<%# app/views/messages/show.html.erb %>
+<%= turbo_frame_tag dom_id(message) do %>
+  <h2><%= message.subject %></h2>
+  <%= link_to "Edit", edit_message_path(message) %>
+<% end %>
+
+<%# app/views/messages/edit.html.erb — same ID, swaps in place %>
+<%= turbo_frame_tag dom_id(message) do %>
+  <%= render "form", message: message %>
+<% end %>
+```
+
+Lazy-loaded frame with placeholder:
+
+```erb
+<%= turbo_frame_tag "comments", src: message_comments_path(message), loading: :lazy do %>
+  <p>Loading comments...</p>
+<% end %>
+```
+
+Tabbed navigation with history:
+
+```erb
+<a href="<%= tab_path %>" data-turbo-frame="tab_content" data-turbo-action="advance">
+  Tab Name
+</a>
+<turbo-frame id="tab_content"><%= yield %></turbo-frame>
+```
+
+Update active state on `turbo:frame-load` (not `turbo:click`):
+
+```javascript
+document.addEventListener("turbo:frame-load", (event) => {
+  if (event.target.id !== "tab_content") return
+  document.querySelectorAll("[data-turbo-frame='tab_content']").forEach((link) => {
+    link.classList.toggle("active", link.href === event.target.src)
+  })
+})
+```
+
+---
+
+## Cache-Safe Views
+
+Turbo caches pages before navigating. Transient UI reappears as stale artifacts unless cleaned up.
+
+```javascript
+document.addEventListener("turbo:before-cache", () => {
+  document.querySelectorAll("[data-expanded]").forEach(el => el.removeAttribute("data-expanded"))
+  document.querySelectorAll(".flash").forEach(el => el.remove())
+  document.querySelectorAll("form").forEach(form => form.reset())
+})
+```
+
+Guard content that depends on fresh data against preview (cached) renders:
+
+```erb
+<% unless request.headers["Purpose"] == "preview" %>
+  <div data-controller="polling"><%= render "metrics", stats: @stats %></div>
+<% end %>
+```
+
+Fragment caching with presenter keys:
+
+```erb
+<% cache presenter.cache_key do %>
+  <%= render partial: "filters/tags", locals: { tags: presenter.tags } %>
+<% end %>
+```
+
+---
+
+## Template-Based Optimistic UI
+
+Store `<turbo-stream>` inside a `<template>` to prevent premature execution:
+
+```html
+<template data-optimistic-stream>
+  <turbo-stream action="append" target="messages">
+    <template>
+      <div class="message message--pending" id="pending_PLACEHOLDER">
+        <p data-placeholder>Sending...</p>
+      </div>
+    </template>
+  </turbo-stream>
+</template>
+```
+
+Clone and dispatch from a Stimulus controller on submit:
+
+```javascript
+submit() {
+  const template = this.templateTarget.content.cloneNode(true)
+  template.querySelector(".message").id = `pending_${Date.now()}`
+  document.body.append(template)
+}
+```

data/data/skills/rails-performance/PROFILING.md

@@ -0,0 +1,106 @@
+# Profiling & Benchmarking
+
+Measure first, optimize second. Profile in the production Ruby version with production-sized data.
+
+---
+
+## Finding N+1 Queries in Development
+
+```ruby
+# Gemfile
+gem "bullet", group: :development
+
+# config/environments/development.rb
+config.after_initialize do
+  Bullet.enable       = true
+  Bullet.rails_logger = true
+  Bullet.add_footer   = true
+end
+```
+
+Check `log/bullet.log` after exercising a feature. Bullet reports N+1 alerts and unused eager loads.
+
+Enable query log tags to trace queries to their source in staging:
+
+```ruby
+# config/application.rb
+config.active_record.query_log_tags_enabled = true
+config.active_record.query_log_tags = [:controller, :action]
+```
+
+---
+
+## Benchmarking with `benchmark-ips`
+
+Compare two implementations before choosing one:
+
+```ruby
+require "benchmark/ips"
+
+Benchmark.ips do |x|
+  x.warmup = 2
+  x.time   = 5
+  x.report("pluck") { User.where(active: true).pluck(:email) }
+  x.report("map")   { User.where(active: true).map(&:email) }
+  x.compare!
+end
+```
+
+Always call `.compare!`. Always warm up. Test with representative data volume.
+
+---
+
+## Rack Mini Profiler
+
+```ruby
+# Gemfile — development and staging only
+gem "rack-mini-profiler"
+gem "stackprof"         # CPU flamegraphs
+gem "memory_profiler"   # allocation profiling
+```
+
+Append `?pp=flamegraph` for CPU flamegraph. Use `?pp=profile-memory` for allocations.
+
+---
+
+## Query Analysis with EXPLAIN
+
+```ruby
+# rails console
+puts Order.where(user_id: 1, status: "pending").order(:created_at).explain
+
+# PostgreSQL — actual execution stats
+ActiveRecord::Base.connection.execute(
+  "EXPLAIN (ANALYZE, BUFFERS) #{Order.where(user_id: 1).to_sql}"
+).each { |r| puts r["QUERY PLAN"] }
+```
+
+Warning signs: `Seq Scan` on large tables (missing index), `rows=` estimate vs actual mismatch (run `ANALYZE`), `Sort` without an index.
+
+---
+
+## Memory Profiling
+
+```ruby
+require "memory_profiler"
+
+report = MemoryProfiler.report { User.where(active: true).map(&:email) }
+report.pretty_print(to_file: "/tmp/mem.txt")
+# Review: allocated_memory_by_gem, allocated_objects_by_location
+```
+
+Allocation reduction checklist:
+- `# frozen_string_literal: true` on every file
+- Extract regex to constants outside loops
+- `pluck` instead of AR objects when only scalars are needed
+- `User.select(:id, :email).find_each` to limit columns in batch jobs
+
+---
+
+## Review Thresholds
+
+| Scenario | Target |
+|---|---|
+| Index page (dev, seeded data) | < 10 queries, < 50ms DB time |
+| Show page | < 5 queries, < 20ms DB time |
+| Batch job over 10k records | Uses `find_each`, < 256MB peak RSS |

data/data/skills/rails-performance/SKILL.md

@@ -0,0 +1,217 @@
+---
+name: rails-performance
+description: Ruby on Rails performance conventions — N+1 prevention, caching, database tuning, benchmarking. Use when optimizing queries, adding caching, or profiling performance.
+---
+
+# Rails Performance Skill
+
+Opinionated conventions for Rails performance. Every pattern has a clear unsafe anti-pattern and safe fix.
+
+**Sub-files:**
+- [PROFILING.md](PROFILING.md) — Profiling, benchmarking, and measurement workflows
+
+---
+
+## N+1 Query Prevention
+
+Always eager load associations accessed in loops:
+
+```ruby
+@posts = Post.includes(:author)                        # single association
+@post  = Post.includes(comments: :author).find(id)    # nested
+```
+
+Counter caches instead of `.count` in loops:
+
+```ruby
+# Model: belongs_to :board, counter_cache: true
+# Migration: add_column :boards, :cards_count, :integer, default: 0, null: false
+board.cards_count   # reads column — no query
+board.cards.count   # fires COUNT — N+1 in loops
+```
+
+---
+
+## Efficient Queries
+
+```ruby
+# pluck returns plain arrays — no AR objects allocated
+emails = User.where(active: true).pluck(:email)
+ids    = Order.where(status: "pending").ids
+
+# exists? → SELECT 1 LIMIT 1 (not .present?, .any?, .count > 0)
+user.orders.where(status: "pending").exists?
+
+# SQL aggregation — never load records to compute in Ruby
+User.order(created_at: :desc)           # NOT .all.sort_by(&:created_at).reverse
+Order.distinct.pluck(:status)           # NOT .all.map(&:status).uniq
+Order.sum(:total_price)                 # NOT .all.sum(&:total_price)
+Product.group(:category_id).count       # preload all counts in one query
+```
+
+**Batch processing for large result sets:**
+
+```ruby
+User.find_each { |u| process(u) }                              # 1000 at a time
+Order.where("created_at < ?", 1.year.ago).find_each(&:archive!)
+Product.where(discontinued: true).find_in_batches(batch_size: 100) do |batch|
+  Index.bulk_delete(batch)
+end
+```
+
+---
+
+## Database Indexing
+
+Index every FK column and every column used in `where`, `order`, `find_by`:
+
+```ruby
+# t.references adds index by default
+create_table :comments do |t|
+  t.references :post, foreign_key: true
+  t.references :user, foreign_key: true
+end
+
+add_index :articles, :status
+add_index :articles, :slug, unique: true
+add_index :users,    :email, where: "active = true", unique: true   # partial
+
+# Composite for multi-column queries
+add_index :orders, [:user_id, :status, :created_at]
+```
+
+Concurrent index creation on live tables:
+
+```ruby
+class AddIndexToOrdersStatus < ActiveRecord::Migration[7.1]
+  disable_ddl_transaction!
+  def change
+    add_index :orders, :status, algorithm: :concurrently
+  end
+end
+```
+
+---
+
+## Caching
+
+**Production cache store — Redis, Memcached, or Solid Cache. Never `:file_store` or `:memory_store`:**
+
+```ruby
+# config/environments/production.rb
+config.cache_store = :redis_cache_store, { url: ENV.fetch("REDIS_URL"), expires_in: 1.hour }
+```
+
+**Fragment caching with auto cache-busting via `cache_key_with_version`:**
+
+```erb
+<% cache(@project) do %>
+  <%= render "projects/detail", project: @project %>
+<% end %>
+
+<%# Collection multi-fetch — one Redis round-trip %>
+<%= render partial: "products/product", collection: @products, cached: true %>
+```
+
+**Application-level caching and per-request memoization:**
+
+```ruby
+def stats
+  Rails.cache.fetch("dashboard/stats", expires_in: 15.minutes) do
+    { revenue: Order.sum(:total), active: User.where("last_sign_in_at > ?", 30.days.ago).count }
+  end
+end
+
+def active_subscription
+  @active_subscription ||= subscriptions.where(active: true).order(created_at: :desc).first
+end
+```
+
+---
+
+## Memory Management
+
+Stream large exports — never build in memory:
+
+```ruby
+def export
+  headers["Content-Disposition"] = 'attachment; filename="users.csv"'
+  headers["Content-Type"] = "text/csv"
+  response.status = 200
+  self.response_body = Enumerator.new do |y|
+    y << CSV.generate_line(["Name", "Email"])
+    User.find_each { |u| y << CSV.generate_line([u.name, u.email]) }
+  end
+end
+```
+
+Always use `deliver_later` and background jobs for slow work:
+
+```ruby
+OrderMailer.confirmation(@order).deliver_later    # NOT deliver_now
+GenerateInvoiceJob.perform_later(@order)          # NOT inline PDF generation
+```
+
+Freeze string literals; extract regex constants out of loops:
+
+```ruby
+# frozen_string_literal: true
+CAPITAL = /\A[A-Z]/
+users.each { |u| u.name.match?(CAPITAL) }
+```
+
+---
+
+## View & Response
+
+```erb
+<%# Single render call with collection caching %>
+<%= render partial: "products/product", collection: @products, cached: true %>
+
+<%# Lazy-load expensive sections %>
+<%= turbo_frame_tag "stats", src: dashboard_stats_path, loading: :lazy do %>
+  <p>Loading...</p>
+<% end %>
+```
+
+Always paginate index actions:
+
+```ruby
+def index
+  @orders = Order.order(created_at: :desc).page(params[:page]).per(25)
+end
+```
+
+---
+
+## Production Configuration
+
+```ruby
+# config/puma.rb
+threads ENV.fetch("RAILS_MIN_THREADS", 5).to_i, ENV.fetch("RAILS_MAX_THREADS", 5).to_i
+workers ENV.fetch("WEB_CONCURRENCY", 2).to_i
+preload_app!
+RubyVM::YJIT.enable if defined?(RubyVM::YJIT) && RubyVM::YJIT.respond_to?(:enable)
+
+# config/environments/production.rb
+config.cache_classes = true
+config.eager_load    = true
+config.assets.compile = false
+config.assets.digest  = true
+```
+
+---
+
+## Check-to-File Mapping
+
+| Changed files | Priority checks |
+|---|---|
+| `app/controllers/**/*.rb` | N+1 includes, `exists?`, pagination, `deliver_later` |
+| `app/models/**/*.rb` | `pluck` vs `map`, SQL aggregation, memoization |
+| `app/views/**/*.erb` | Fragment caching, `render collection:`, lazy frames |
+| `app/jobs/**/*.rb` | `find_each`, `find_in_batches`, memory |
+| `db/migrate/**/*.rb` | FK indexes, concurrent index, composite indexes |
+| `config/environments/production.rb` | Cache store, `eager_load`, assets |
+| `config/puma.rb` | Threads/workers, YJIT |
+
+See [PROFILING.md](PROFILING.md) for measurement, benchmarking, and query analysis.