rubyn-code 0.1.0

data/skills/design_patterns/builder.md

@@ -0,0 +1,158 @@
+# Design Pattern: Builder
+
+## Pattern
+
+Construct complex objects step by step. The Builder pattern lets you produce different representations of an object using the same construction process. In Ruby, builders are often implemented as chainable method calls or configuration blocks.
+
+```ruby
+# Builder with chainable methods — idiomatic Ruby
+class PromptBuilder
+  def initialize
+    @system_parts = []
+    @messages = []
+    @model = "claude-haiku-4-5-20251001"
+    @max_tokens = 4096
+    @temperature = 0.0
+  end
+
+  def system(content)
+    @system_parts << content
+    self
+  end
+
+  def best_practice(document)
+    @system_parts << "## Best Practice: #{document.title}\n\n#{document.content}"
+    self
+  end
+
+  def codebase_context(embeddings)
+    context = embeddings.map { |e| "# #{e.file_path}\n```ruby\n#{e.chunk_content}\n```" }.join("\n\n")
+    @system_parts << "## Relevant Codebase Context\n\n#{context}"
+    self
+  end
+
+  def user(content)
+    @messages << { role: "user", content: content }
+    self
+  end
+
+  def assistant(content)
+    @messages << { role: "assistant", content: content }
+    self
+  end
+
+  def model(name)
+    @model = name
+    self
+  end
+
+  def max_tokens(n)
+    @max_tokens = n
+    self
+  end
+
+  def temperature(t)
+    @temperature = t
+    self
+  end
+
+  def build
+    {
+      model: @model,
+      max_tokens: @max_tokens,
+      temperature: @temperature,
+      system: @system_parts.join("\n\n---\n\n"),
+      messages: @messages
+    }
+  end
+end
+
+# Usage — reads like a recipe
+prompt = PromptBuilder.new
+  .system("You are Rubyn, an expert Ruby and Rails coding assistant.")
+  .best_practice(service_objects_doc)
+  .best_practice(callbacks_doc)
+  .codebase_context(relevant_embeddings)
+  .user("Refactor this controller action into a service object:\n\n```ruby\n#{code}\n```")
+  .model("claude-haiku-4-5-20251001")
+  .max_tokens(4096)
+  .build
+```
+
+Builder with block configuration — Ruby convention:
+
+```ruby
+class QueryBuilder
+  attr_reader :scope
+
+  def initialize(base_scope)
+    @scope = base_scope
+  end
+
+  def self.build(base_scope, &block)
+    builder = new(base_scope)
+    builder.instance_eval(&block) if block
+    builder.scope
+  end
+
+  def where(**conditions)
+    @scope = @scope.where(conditions)
+  end
+
+  def search(query)
+    return unless query.present?
+    @scope = @scope.where("name ILIKE ?", "%#{query}%")
+  end
+
+  def status(value)
+    return unless value.present?
+    @scope = @scope.where(status: value)
+  end
+
+  def date_range(from:, to:)
+    @scope = @scope.where(created_at: from..to) if from && to
+  end
+
+  def sort_by(column, direction = :asc)
+    @scope = @scope.order(column => direction)
+  end
+
+  def paginate(page:, per: 25)
+    @scope = @scope.page(page).per(per)
+  end
+end
+
+# Usage with block
+orders = QueryBuilder.build(current_user.orders) do
+  status params[:status]
+  search params[:q]
+  date_range from: params[:from], to: params[:to]
+  sort_by :created_at, :desc
+  paginate page: params[:page]
+end
+```
+
+## Why This Is Good
+
+- **Step-by-step construction.** Complex objects are built incrementally. Each step is named and self-documenting. The final `build` call assembles everything.
+- **Optional steps.** Not every prompt needs best practices or codebase context. The builder doesn't care which steps are called or in what order.
+- **Chainable API is readable.** `.system(...).best_practice(...).user(...)` reads as a sequence of construction steps. It's clearer than a constructor with 8 keyword arguments.
+- **Separates construction from representation.** The same builder process can produce different outputs — a hash for the API, a string for logging, an object for testing.
+- **Block form is idiomatic Ruby.** `QueryBuilder.build(scope) { status "active" }` follows Ruby conventions (like `Faraday.new { |f| f.adapter :net_http }`).
+
+## When To Apply
+
+- **Objects with many optional parts.** An API request with optional system prompt, codebase context, conversation history, model selection, and temperature.
+- **Objects constructed in different configurations.** A query that sometimes has filters, sometimes has sorting, sometimes has pagination — but never all of them.
+- **When a constructor has 5+ parameters.** The builder replaces a long argument list with named, chainable steps.
+- **Testing.** Builders make it easy to create test fixtures with specific configurations without specifying every field.
+
+## When NOT To Apply
+
+- **Simple objects with 2-3 required fields.** `Order.new(user: user, total: 100)` doesn't need a builder.
+- **Objects that are always constructed the same way.** If every construction uses the same steps, a factory method is simpler.
+- **Don't create a builder just for one call site.** Builders shine when used from multiple places with different configurations.
+
+## Rails Examples
+
+Rails uses the builder pattern extensively — `Arel` query building, `ActionMailer` message construction, `ActiveStorage` attachment configuration. Follow the same pattern for your domain objects.

data/skills/design_patterns/command.md

@@ -0,0 +1,126 @@
+# Design Pattern: Command
+
+## Pattern
+
+Encapsulate a request as an object, allowing you to parameterize clients with different requests, queue requests, log them, and support undo operations. In Ruby/Rails, service objects are already a form of the Command pattern — each one encapsulates a single operation.
+
+```ruby
+# Commands as objects — queueable, loggable, undoable
+class Commands::Base
+  attr_reader :executed_at, :result
+
+  def execute
+    raise NotImplementedError
+  end
+
+  def undo
+    raise NotImplementedError, "#{self.class} does not support undo"
+  end
+
+  def description
+    raise NotImplementedError
+  end
+end
+
+class Commands::ChangeOrderStatus < Commands::Base
+  def initialize(order, new_status, actor:)
+    @order = order
+    @new_status = new_status
+    @actor = actor
+    @previous_status = order.status
+  end
+
+  def execute
+    @order.update!(status: @new_status)
+    @executed_at = Time.current
+    AuditLog.record(actor: @actor, action: description, target: @order)
+    @result = :success
+  end
+
+  def undo
+    @order.update!(status: @previous_status)
+    AuditLog.record(actor: @actor, action: "Undo: #{description}", target: @order)
+  end
+
+  def description
+    "Changed order #{@order.reference} from #{@previous_status} to #{@new_status}"
+  end
+end
+
+class Commands::ApplyDiscount < Commands::Base
+  def initialize(order, discount_code, actor:)
+    @order = order
+    @discount_code = discount_code
+    @actor = actor
+    @previous_discount = order.discount_amount
+  end
+
+  def execute
+    discount = Discount.active.find_by!(code: @discount_code)
+    amount = discount.calculate(@order.subtotal)
+    @order.update!(discount_amount: amount, discount_code: @discount_code)
+    @executed_at = Time.current
+    @result = :success
+  end
+
+  def undo
+    @order.update!(discount_amount: @previous_discount, discount_code: nil)
+  end
+
+  def description
+    "Applied discount #{@discount_code} to order #{@order.reference}"
+  end
+end
+
+# Command history for undo support
+class CommandHistory
+  def initialize
+    @history = []
+  end
+
+  def execute(command)
+    command.execute
+    @history.push(command)
+    command
+  end
+
+  def undo_last
+    command = @history.pop
+    return unless command
+    command.undo
+    command
+  end
+
+  def log
+    @history.map { |cmd| "#{cmd.executed_at}: #{cmd.description}" }
+  end
+end
+
+# Usage
+history = CommandHistory.new
+history.execute(Commands::ChangeOrderStatus.new(order, "confirmed", actor: admin))
+history.execute(Commands::ApplyDiscount.new(order, "SAVE10", actor: admin))
+
+# Undo last action
+history.undo_last  # Reverses the discount
+```
+
+## Why This Is Good
+
+- **Operations are first-class objects.** Each command can be queued, logged, serialized, and undone. You can't do this with bare method calls.
+- **Audit trail is built in.** Every command has a `description` and `executed_at`. The history is an automatic audit log.
+- **Undo support.** Each command stores the state needed to reverse itself. Admin actions, bulk operations, and user-facing "undo" features are straightforward.
+- **Deferred execution.** Commands can be serialized and executed later — in a background job, after approval, or in a batch.
+
+## When To Apply
+
+- **Admin actions that need audit trails.** Status changes, refunds, account modifications — wrap each in a command that logs who did what.
+- **User-facing undo.** "Undo archive", "undo delete", "undo status change" — commands store previous state.
+- **Batch operations.** Collect multiple commands, validate them all, then execute as a group.
+- **Background job payloads.** Serialize a command and enqueue it. The job deserializes and executes.
+
+## When NOT To Apply
+
+- **Simple CRUD without undo or audit.** A standard `Order.create!(params)` doesn't need a Command wrapper.
+- **Your existing service objects already work.** If service objects handle your use case without undo or queueing needs, don't add Command on top.
+- **Fire-and-forget operations.** If you never need to undo or replay the action, a plain service object is simpler.

data/skills/design_patterns/composite.md

@@ -0,0 +1,147 @@
+# Design Pattern: Composite
+
+## Pattern
+
+Compose objects into tree structures to represent part-whole hierarchies. The Composite pattern lets clients treat individual objects and compositions of objects uniformly — the same interface for a single item and a group of items.
+
+```ruby
+# Permission system — individual permissions and permission groups share the same interface
+
+class Permission
+  attr_reader :name
+
+  def initialize(name)
+    @name = name
+  end
+
+  def grants?(action)
+    name == action
+  end
+
+  def all_permissions
+    [name]
+  end
+
+  def to_s
+    name
+  end
+end
+
+class PermissionGroup
+  attr_reader :name
+
+  def initialize(name)
+    @name = name
+    @children = []
+  end
+
+  def add(permission)
+    @children << permission
+    self
+  end
+
+  def grants?(action)
+    @children.any? { |child| child.grants?(action) }
+  end
+
+  def all_permissions
+    @children.flat_map(&:all_permissions)
+  end
+
+  def to_s
+    "#{name}: [#{@children.map(&:to_s).join(', ')}]"
+  end
+end
+
+# Build a permission tree
+read_code = Permission.new("code:read")
+write_code = Permission.new("code:write")
+delete_code = Permission.new("code:delete")
+
+code_admin = PermissionGroup.new("code_admin")
+  .add(read_code)
+  .add(write_code)
+  .add(delete_code)
+
+read_billing = Permission.new("billing:read")
+manage_billing = Permission.new("billing:manage")
+
+billing_admin = PermissionGroup.new("billing_admin")
+  .add(read_billing)
+  .add(manage_billing)
+
+super_admin = PermissionGroup.new("super_admin")
+  .add(code_admin)      # Group containing group
+  .add(billing_admin)   # Group containing group
+
+# Uniform interface — works the same for single permissions and groups
+read_code.grants?("code:read")        # true
+code_admin.grants?("code:read")       # true
+super_admin.grants?("billing:manage") # true — traverses the tree
+super_admin.all_permissions
+# => ["code:read", "code:write", "code:delete", "billing:read", "billing:manage"]
+```
+
+Rails-practical example — pricing rules:
+
+```ruby
+# Single rule and rule groups share the same interface
+class Pricing::FlatDiscount
+  def initialize(amount)
+    @amount = amount
+  end
+
+  def apply(price)
+    [price - @amount, 0].max
+  end
+end
+
+class Pricing::PercentDiscount
+  def initialize(percent)
+    @percent = percent
+  end
+
+  def apply(price)
+    price * (1 - @percent / 100.0)
+  end
+end
+
+class Pricing::DiscountChain
+  def initialize
+    @discounts = []
+  end
+
+  def add(discount)
+    @discounts << discount
+    self
+  end
+
+  def apply(price)
+    @discounts.reduce(price) { |p, discount| discount.apply(p) }
+  end
+end
+
+# Compose discounts
+holiday_deal = Pricing::DiscountChain.new
+  .add(Pricing::PercentDiscount.new(10))   # 10% off first
+  .add(Pricing::FlatDiscount.new(5_00))     # Then $5 off
+
+final_price = holiday_deal.apply(100_00)  # $100 → $90 → $85
+```
+
+## Why This Is Good
+
+- **Uniform interface.** `grants?("code:read")` works on a single permission, a group, or a tree of groups. The caller never checks types.
+- **Recursive composition.** Groups can contain other groups. `super_admin` contains `code_admin` which contains individual permissions. Any depth works.
+- **Easy to extend.** New permission types (time-limited, IP-restricted) just implement `grants?` and `all_permissions`. They plug into any group.
+
+## When To Apply
+
+- **Tree structures** — menus, categories, org charts, file systems, permission hierarchies.
+- **Part-whole relationships** — a single discount and a chain of discounts, a single validator and a validator pipeline.
+- **When clients need to treat single items and collections identically.**
+
+## When NOT To Apply
+
+- **Flat collections.** If items don't nest, use a simple array. Don't build a Composite for a list.
+- **When the leaf and composite have very different interfaces.** If a single permission and a permission group need fundamentally different methods, Composite adds forced uniformity.

data/skills/design_patterns/decorator.md

@@ -0,0 +1,204 @@
+# Design Pattern: Decorator
+
+## Pattern
+
+Attach additional behavior to an object dynamically by wrapping it in a decorator object. The decorator forwards method calls to the wrapped object and adds behavior before, after, or around the delegation. In Ruby, decorators are often implemented with `SimpleDelegator` or `method_missing`, but explicit delegation is clearest.
+
+```ruby
+# Base class — the object to be decorated
+class Ai::CompletionClient
+  def complete(messages, model:, max_tokens:)
+    response = Anthropic::Client.new.messages.create(
+      model: model,
+      max_tokens: max_tokens,
+      messages: messages
+    )
+    CompletionResult.new(
+      content: response.content.first.text,
+      input_tokens: response.usage.input_tokens,
+      output_tokens: response.usage.output_tokens
+    )
+  end
+end
+
+# Decorator: adds logging around the real call
+class Ai::LoggingDecorator
+  def initialize(client)
+    @client = client
+  end
+
+  def complete(messages, model:, max_tokens:)
+    Rails.logger.info("[AI] Requesting #{model} with #{messages.length} messages")
+    start = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+
+    result = @client.complete(messages, model: model, max_tokens: max_tokens)
+
+    elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - start
+    Rails.logger.info("[AI] Completed in #{elapsed.round(2)}s — #{result.input_tokens}in/#{result.output_tokens}out")
+
+    result
+  end
+end
+
+# Decorator: adds caching
+class Ai::CachingDecorator
+  def initialize(client, cache: Rails.cache, ttl: 1.hour)
+    @client = client
+    @cache = cache
+    @ttl = ttl
+  end
+
+  def complete(messages, model:, max_tokens:)
+    cache_key = "ai:#{Digest::SHA256.hexdigest(messages.to_json)}:#{model}"
+
+    @cache.fetch(cache_key, expires_in: @ttl) do
+      @client.complete(messages, model: model, max_tokens: max_tokens)
+    end
+  end
+end
+
+# Decorator: adds retry logic
+class Ai::RetryDecorator
+  def initialize(client, max_retries: 3)
+    @client = client
+    @max_retries = max_retries
+  end
+
+  def complete(messages, model:, max_tokens:)
+    retries = 0
+    begin
+      @client.complete(messages, model: model, max_tokens: max_tokens)
+    rescue Faraday::TimeoutError, Faraday::ServerError => e
+      retries += 1
+      raise if retries > @max_retries
+      sleep(2**retries + rand(0.0..0.5))
+      retry
+    end
+  end
+end
+
+# Compose decorators — each wraps the previous one
+client = Ai::CompletionClient.new
+client = Ai::RetryDecorator.new(client)
+client = Ai::CachingDecorator.new(client)
+client = Ai::LoggingDecorator.new(client)
+
+# The caller sees ONE object with ONE interface
+result = client.complete(messages, model: "claude-haiku-4-5-20251001", max_tokens: 4096)
+# Logs → checks cache → retries on failure → calls Anthropic
+```
+
+Using `SimpleDelegator` for view decorators (presenters):
+
+```ruby
+class OrderPresenter < SimpleDelegator
+  def formatted_total
+    "$#{format('%.2f', total)}"
+  end
+
+  def status_badge
+    case status
+    when "pending" then '<span class="badge bg-warning">Pending</span>'
+    when "shipped" then '<span class="badge bg-info">Shipped</span>'
+    when "delivered" then '<span class="badge bg-success">Delivered</span>'
+    else '<span class="badge bg-secondary">Unknown</span>'
+    end.html_safe
+  end
+
+  def created_at_formatted
+    created_at.strftime("%B %d, %Y at %I:%M %p")
+  end
+end
+
+# Usage in controller
+@order = OrderPresenter.new(Order.find(params[:id]))
+
+# In the view, all Order methods work plus the presenter methods
+<%= @order.formatted_total %>
+<%= @order.status_badge %>
+<%= @order.user.name %>  <!-- delegated to the real Order -->
+```
+
+## Why This Is Good
+
+- **Composable behaviors.** Logging, caching, and retry are separate concerns, each in its own class. You compose them like LEGO — add or remove as needed.
+- **Same interface throughout.** Every decorator responds to `complete(messages, model:, max_tokens:)`. The caller doesn't know or care how many decorators are stacked.
+- **Open/Closed compliant.** Adding rate limiting means writing a `RateLimitDecorator` — not modifying the client, the logger, or the cache.
+- **Testable in isolation.** Test `RetryDecorator` by wrapping a fake client that fails twice then succeeds. No real HTTP, no logging, no caching involved.
+- **Presenters keep views clean.** `@order.formatted_total` is cleaner than `number_to_currency(@order.total)` scattered across 10 views.
+
+## Anti-Pattern
+
+Putting all cross-cutting concerns inside the base class:
+
+```ruby
+class Ai::CompletionClient
+  def complete(messages, model:, max_tokens:)
+    cache_key = "ai:#{Digest::SHA256.hexdigest(messages.to_json)}"
+    cached = Rails.cache.read(cache_key)
+    return cached if cached
+
+    Rails.logger.info("[AI] Requesting #{model}")
+    start = Time.now
+
+    retries = 0
+    begin
+      response = Anthropic::Client.new.messages.create(
+        model: model, max_tokens: max_tokens, messages: messages
+      )
+    rescue Faraday::TimeoutError
+      retries += 1
+      retry if retries <= 3
+      raise
+    end
+
+    elapsed = Time.now - start
+    Rails.logger.info("[AI] Completed in #{elapsed}s")
+
+    result = CompletionResult.new(content: response.content.first.text)
+    Rails.cache.write(cache_key, result, expires_in: 1.hour)
+    result
+  end
+end
+```
+
+## Why This Is Bad
+
+- **One 30-line method with 4 responsibilities.** API call, logging, caching, and retry are tangled together. Modifying retry logic means reading through cache and logging code.
+- **Can't disable caching for tests.** The cache is hardcoded. Tests either hit the cache (stale results) or need `Rails.cache.clear` before every test.
+- **Can't reuse retry logic.** If the embedding client also needs retry, you duplicate the retry block. With a decorator, `RetryDecorator.new(embedding_client)` reuses it.
+
+## When To Apply
+
+- **Cross-cutting concerns** — logging, caching, retry, rate limiting, metrics, authentication wrapping. Each is a decorator.
+- **View presentation logic** — formatting dates, currencies, status badges, display names. Use `SimpleDelegator` presenters.
+- **Feature toggles** — a decorator that conditionally enables new behavior while forwarding to the old behavior by default.
+- **API response transformation** — a decorator that normalizes different API response formats into a consistent internal structure.
+
+## When NOT To Apply
+
+- **One behavior that won't be reused.** If only the AI client needs retry logic and nothing else ever will, putting retry inline is simpler than a decorator class.
+- **Deep stacks obscure behavior.** If you stack 7 decorators, debugging which one modified the response is difficult. Keep stacks to 3-4 max.
+- **Don't decorate ActiveRecord models for persistence logic.** Use service objects. Decorators are for presentation and cross-cutting concerns, not business logic.
+
+## Edge Cases
+
+**`Module#prepend` as an inline decorator:**
+
+```ruby
+module Logging
+  def complete(messages, model:, max_tokens:)
+    Rails.logger.info("[AI] Requesting #{model}")
+    result = super
+    Rails.logger.info("[AI] Done: #{result.input_tokens} tokens")
+    result
+  end
+end
+
+Ai::CompletionClient.prepend(Logging)
+```
+
+This is Ruby's most concise decorator pattern but less flexible — it modifies the class globally rather than per-instance.
+
+**Draper gem for view decorators:**
+If the team uses Draper, follow its conventions. Otherwise, `SimpleDelegator` is lighter and framework-free.