ask-rails 0.1.0 → 0.2.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: '081f609a014a72157291794a40c580ed6fabb625c2db0c7511538acae540ea9b'
-  data.tar.gz: 1445552073a10f1fbae78f63d7220c894efbcb1cd6433f7aef8f977e4374b1e6
+  metadata.gz: 5853a59ba85a4d0de9f171ddce9934c5928f45bbc3acc5f5c95940a6779b03d6
+  data.tar.gz: 5a65227d1e17a2525010c96dbb34b8e77ab0fe9a54b03ced8a9149b21880af90
 SHA512:
-  metadata.gz: c0fcb6d2a6f53c8fa89dafd2ce2d6f3393c305a0df0cbfe67472798a9973032645e81ccec5517a855bba25e90572ac5c1100ba4d73b5e98e70ab329629e1ad99
-  data.tar.gz: 5227ec0290f2177f844922038439c99b7bfd8d0d35360b7256206825f220b0323d8d139117000169336f50242191b200f0896a79379d8769996aede9b2f12d36
+  metadata.gz: 6123792315516dee1f33f6ea34586d40c8fb62e4b0c1981b892326d3eb1abc59757115f84b5cf242cad572bb31673b29aff9c92a036e6910e7af85b6a72d39ae
+  data.tar.gz: 801c37b5ab3969c36480814263d8a6373faca69f1d06cfa24bce21b53ac6ecd49a3989c2909626fb11ea233c99ecf7c4f66c259e8b5a8854e64197bef5ee9a16

data/lib/ask/rails/persistence.rb

@@ -4,39 +4,31 @@ module Ask
   module Rails
     class Persistence
       def initialize(model_class: nil)
-        @model_class = model_class || default_model_class
+        @model_class = model_class
       end
 
       def save(session_id, data)
-        record = @model_class.find_or_initialize_by(session_id: session_id)
+        record = model_class.find_or_initialize_by(session_id: session_id)
         record.update!(data: data)
       end
 
       def load(session_id)
-        record = @model_class.find_by(session_id: session_id)
+        record = model_class.find_by(session_id: session_id)
         record&.data
       end
 
       def delete(session_id)
-        @model_class.where(session_id: session_id).delete_all
+        model_class.where(session_id: session_id).delete_all
       end
 
       def list
-        @model_class.pluck(:session_id)
+        model_class.pluck(:session_id)
       end
 
       private
 
-      def default_model_class
-        # Lazy reference so the model class doesn't need to exist at load time
-        ask_session_model = Class.new(::ActiveRecord::Base) do
-          self.table_name = "ask_sessions"
-        end
-        # Store it as a constant so it's reusable
-        unless Object.const_defined?(:AskSession)
-          Object.const_set(:AskSession, ask_session_model)
-        end
-        AskSession
+      def model_class
+        @model_class || (raise "No model class configured. Use Persistence.new(model_class: MyModel)")
       end
     end
   end

data/lib/ask/rails/service_discovery.rb

@@ -14,10 +14,9 @@ module Ask
         service_gems.each do |name|
           begin
             require "#{name.tr("-", "/")}/context"
-            mod = name.camelize.constantize
-            contexts << mod if mod.const_defined?(:DESCRIPTION)
+            mod = name.split("-").map(&:capitalize).join.constantize
+            contexts << mod if mod.respond_to?(:const_defined?) && mod.const_defined?(:DESCRIPTION)
           rescue LoadError, NameError
-            # No context module for this gem
           end
         end
 
@@ -34,7 +33,8 @@ module Ask
         sections = ["## Available Services"]
 
         contexts.each do |mod|
-          sections << "### #{mod.name.demodulize}"
+          name = mod.respond_to?(:name) ? mod.name.to_s.split("::").last || "Unknown" : "Unknown"
+          sections << "### #{name}"
           sections << mod::DESCRIPTION if mod.const_defined?(:DESCRIPTION)
           sections << "Documentation: #{mod::DOCS_URL}" if mod.const_defined?(:DOCS_URL)
           sections << "Authentication: #{mod::AUTH_HOW}" if mod.const_defined?(:AUTH_HOW)

data/lib/ask/rails/tools/query_database.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Tools
+      class QueryDatabase < Ask::Rails::Tool
+        description "Run a read-only SQL query against the application database. " \
+                     "Returns columns and rows. Only SELECT queries are allowed in production."
+
+        param :sql,   type: :string, desc: "SQL query (SELECT only in production)", required: true
+        param :limit, type: :integer, desc: "Max rows to return (default 50)", required: false
+
+        WRITE_STATEMENTS = /\A\s*(INSERT|UPDATE|DELETE|DROP|TRUNCATE|ALTER|CREATE|GRANT|REVOKE)\b/i
+
+        def execute(sql:, limit: 50)
+          sql = sql.strip
+
+          if WRITE_STATEMENTS.match?(sql)
+            return Ask::Result.failure(
+              "Only SELECT queries are allowed. Write statements (#{sql.match(WRITE_STATEMENTS)[1]}) are rejected in all environments."
+            )
+          end
+
+          if ::Rails.env.production? && !sql.match?(/\A\s*SELECT\b/i)
+            return Ask::Result.failure(
+              "Only SELECT queries are allowed in the production environment."
+            )
+          end
+
+          pool = ActiveRecord::Base.connection_pool
+          pool.with_connection do |conn|
+            limited_sql = sql.match?(/\bLIMIT\b/i) ? sql : "#{sql.chomp(';')} LIMIT #{limit.to_i}"
+            result = conn.exec_query(limited_sql)
+            columns = result.columns
+            rows = result.rows.first(limit.to_i).map { |row| build_row(row, columns) }
+            {
+              columns: columns,
+              rows: rows,
+              count: rows.size,
+              truncated: result.rows.size > limit.to_i
+            }
+          end
+        rescue ActiveRecord::StatementInvalid => e
+          Ask::Result.failure("SQL error: #{e.message}")
+        rescue ActiveRecord::ConnectionNotEstablished => e
+          Ask::Result.failure("Database not connected: #{e.message}. Verify the database is running and Rails is connected.")
+        end
+
+        private
+
+        def build_row(row, columns)
+          columns.each_with_index.each_with_object({}) do |(col, i), hash|
+            value = row[i]
+            hash[col] = sanitize_value(value)
+          end
+        end
+
+        def sanitize_value(value)
+          return "[BINARY DATA]" if binary_value?(value)
+          return value.iso8601 if value.respond_to?(:iso8601)
+          value
+        end
+
+        def binary_value?(value)
+          value.is_a?(String) && value.encoding == Encoding::ASCII_8BIT && value.bytesize > 0
+        rescue
+          false
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/tools/read_log.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Tools
+      class ReadLog < Ask::Rails::Tool
+        description "Read application log files with filtering. Supports Rails default " \
+                     "logger and log rotation. Reads from the end of the file (most recent first)."
+
+        param :lines,  type: :integer, desc: "Number of recent lines (default 50, max 500)", required: false
+        param :level,  type: :string, desc: "Filter by level: ERROR, WARN, INFO, DEBUG", required: false
+        param :search, type: :string, desc: "Search term (plain text, case-insensitive)", required: false
+        param :file,   type: :string, desc: "Log file name (default: log/<env>.log)", required: false
+
+        MAX_LINES = 500
+        LEVEL_PATTERNS = {
+          "ERROR" => /\bERROR\b/i,
+          "WARN"  => /\bWARN\b/i,
+          "INFO"  => /\bINFO\b/i,
+          "DEBUG" => /\bDEBUG\b/i
+        }.freeze
+
+        def execute(lines: 50, level: nil, search: nil, file: nil)
+          max_lines = [lines.to_i, MAX_LINES].min
+          log_path = resolve_log_path(file)
+
+          unless log_path.exist?
+            return Ask::Result.failure(
+              "Log file not found: #{log_path}. The application may not have written any logs yet."
+            )
+          end
+
+          raw_lines = read_all_log_files(log_path)
+          return { lines: [], total_lines: 0, path: log_path.to_s } if raw_lines.empty?
+
+          filtered = apply_filters(raw_lines, level: level, search: search)
+          recent = filtered.last(max_lines).map(&:chomp)
+
+          {
+            lines: recent,
+            total_lines: raw_lines.size,
+            matched_lines: filtered.size,
+            path: log_path.to_s,
+            filters_applied: { level: level, search: search }.compact
+          }
+        end
+
+        private
+
+        def resolve_log_path(custom_path)
+          return rails_root.join(custom_path) if custom_path
+          rails_root.join("log", "#{Rails.env}.log")
+        end
+
+        # Read from rotated archives too: log/production.log, .1, .2.gz, etc.
+        def read_all_log_files(log_path)
+          all_content = +""
+          rotated_files(log_path).each do |path|
+            content = read_file_content(path)
+            all_content.prepend(content) if content
+          end
+          all_content.lines
+        end
+
+        def rotated_files(log_path)
+          dir = log_path.dirname
+          base = log_path.basename.to_s
+          # Primary file, then rotated files in reverse order (oldest first, then primary last)
+          pattern = File.join(dir, "#{base}.*")
+          rotations = Dir[pattern].sort_by { |f| extract_rotation_number(f) }
+          # Primary file is read last (most recent)
+          rotations + [log_path.to_s]
+        end
+
+        def extract_rotation_number(path)
+          File.basename(path).sub(/.*\.(\d+)(\.gz)?$/, '\1').to_i
+        rescue
+          0
+        end
+
+        def read_file_content(path)
+          if path.to_s.end_with?(".gz")
+            Zlib::GzipReader.open(path.to_s) { |gz| gz.read }
+          else
+            File.read(path.to_s)
+          end
+        rescue => e
+          warn "[ReadLog] Could not read #{path}: #{e.message}"
+          nil
+        end
+
+        def read_tail(path, max_bytes)
+          return "" unless path.exist?
+
+          size = path.size
+          return path.read if size <= max_bytes
+
+          File.open(path, "rb") do |f|
+            f.seek(-max_bytes, IO::SEEK_END)
+            partial = f.read(max_bytes)
+            if (idx = partial.index("\n"))
+              partial[idx + 1..]
+            else
+              partial
+            end
+          end
+        end
+
+        def apply_filters(lines, level: nil, search: nil)
+          filtered = lines
+          filtered = filtered.select { |l| LEVEL_PATTERNS.fetch(level) { // }.match?(l) } if level
+          filtered = filtered.select { |l| l.downcase.include?(search.downcase) } if search
+          filtered
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/tools/read_model.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+module Ask
+  module Rails
+    module Tools
+      class ReadModel < Ask::Rails::Tool
+        description "Inspect an ActiveRecord model — columns, associations, validations, " \
+                     "scopes, and indexes. Returns structured data the agent can act on."
+
+        param :name,   type: :string, desc: "Model class name (e.g. 'User', 'Blog::Post')", required: true
+        param :detail, type: :string, desc: "Which details: 'all' (default), 'columns', 'associations', 'validations', 'scopes'", required: false
+
+        def execute(name:, detail: "all")
+          klass = safe_constantize(name)
+          return Ask::Result.failure("Model '#{name}' not found or is not an ActiveRecord model.") unless klass
+
+          result = { name: klass.name, table_name: klass.table_name }
+
+          result[:primary_key] = klass.primary_key if klass.respond_to?(:primary_key)
+
+          if %w[all columns].include?(detail)
+            result[:columns] = klass.columns.map { |c|
+              entry = { name: c.name, type: c.type, null: c.null, default: c.default }
+              entry[:primary_key] = true if c.name == klass.primary_key
+              entry
+            }
+          end
+
+          if %w[all associations].include?(detail)
+            result[:associations] = klass.reflect_on_all_associations.group_by(&:macro).transform_values { |refs|
+              refs.map { |a|
+                entry = { name: a.name, class_name: a.class_name }
+                entry[:through] = a.options[:through] if a.options[:through]
+                entry[:source] = a.options[:source] if a.options[:source]
+                entry[:foreign_key] = a.foreign_key if a.respond_to?(:foreign_key)
+                entry
+              }
+            }
+          end
+
+          if %w[all scopes].include?(detail) && klass.respond_to?(:all)
+            result[:scopes] = klass.methods(false)
+              .reject { |m| m.to_s.end_with?("=", "!", "?") || %i[new allocate inspect to_s].include?(m) }
+              .map(&:to_s).sort
+          end
+
+          if %w[all validations].include?(detail)
+            result[:validators] = klass.validators.map { |v|
+              {
+                attribute: v.attributes.first&.to_s,
+                kind: v.kind,
+                options: v.options.reject { |k, _| k == :if }
+              }
+            }.reject { |v| v[:attribute].nil? }
+          end
+
+          result
+        end
+
+        private
+
+        def safe_constantize(name)
+          klass = name.safe_constantize
+          return nil unless klass
+          return nil unless klass < ActiveRecord::Base
+          klass
+        rescue
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/ask/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Ask
   module Rails
-    VERSION = "0.1.0"
+    VERSION = "0.2.1"
   end
 end

data/lib/ask/rails.rb

@@ -74,3 +74,6 @@ require_relative "rails/tools/read_file"
 require_relative "rails/tools/run_command"
 require_relative "rails/tools/search_codebase"
 require_relative "rails/tools/read_routes"
+require_relative "rails/tools/query_database"
+require_relative "rails/tools/read_model"
+require_relative "rails/tools/read_log"

data/lib/ask/skills/rails.db_debug/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: rails.db_debug
+description: Step-by-step methodology for debugging database performance issues in Rails
+---
+
+Use this skill when investigating slow queries, N+1 problems, missing indexes, or
+general database performance issues in a Rails application.
+
+## Step 1: Identify the Slow Queries
+
+Use `ReadLog.new.call(lines: 200, search: "SELECT")` to find recent database
+queries in the application log. Look for:
+
+- Queries taking > 100ms (look for "duration:" or "↳" markers in Rails logs)
+- Repetitive queries with the same structure (potential N+1)
+- Queries running in loops (same query, different IDs)
+
+If you need more detail, narrow the search: `ReadLog.new.call(lines: 500, level: "WARN")`.
+
+## Step 2: Understand the Schema
+
+For each model involved in the slow queries, inspect it:
+
+```ruby
+ReadModel.new.call(name: "User")
+ReadModel.new.call(name: "Post")
+```
+
+Focus on:
+- **Columns** — are there columns that look like foreign keys without indexes?
+- **Associations** — what associations exist and what `class_name` do they use?
+- **Validators** — any database-level constraints that could be missing?
+
+Run `ReadModel.new.call(name: "User", detail: "columns")` if you only need columns.
+
+## Step 3: Check for Missing Indexes
+
+Query the database for actual indexes:
+
+```ruby
+QueryDatabase.new.call(
+  sql: "SELECT tablename, indexname, indexdef FROM pg_indexes WHERE schemaname = 'public' ORDER BY tablename, indexname",
+  limit: 200
+)
+```
+
+Look for:
+- Foreign key columns that lack indexes (e.g. `user_id` without index)
+- Columns used in `WHERE` clauses without indexes
+- Composite indexes that could cover multiple query patterns
+
+If an index is missing, check if adding one would help:
+```ruby
+QueryDatabase.new.call(
+  sql: "EXPLAIN ANALYZE SELECT * FROM posts WHERE user_id = 1",
+  limit: 10
+)
+```
+
+## Step 4: Detect N+1 Queries
+
+N+1 manifests as the same query repeated with different IDs:
+
+```ruby
+# Search for repetitive query patterns
+ReadLog.new.call(lines: 500, search: "WHERE.*IN")
+```
+
+Common N+1 patterns:
+- Loading `Post.all` then accessing `post.comments` individually
+- Loading `User.all` then accessing `user.profile` individually
+- Serializing associations in views without eager loading
+
+Fix with `.includes(:association)`, `.eager_load(:association)`, or
+`.preload(:association)`.
+
+## Step 5: Profile Slow Queries with EXPLAIN
+
+For any identified slow query, get the execution plan:
+
+```ruby
+QueryDatabase.new.call(
+  sql: "EXPLAIN (ANALYZE, BUFFERS) SELECT posts.* FROM posts WHERE posts.user_id = 1 ORDER BY posts.created_at DESC LIMIT 20",
+  limit: 10
+)
+```
+
+What to look for in explain output:
+- **Sequential scans** (`Seq Scan`) — missing index
+- **Sort operations** — missing index on sort column
+- **Nested loop joins** with high row counts — missing composite index
+- **Bitmap heap scans** with high costs — index may be suboptimal
+
+If `ANALYZE` takes too long, use `EXPLAIN (BUFFERS)` without `ANALYZE` for cost estimates.
+
+## Step 6: Check Bulk Loading and Batch Operations
+
+If the issue involves importing or updating many records:
+
+```ruby
+QueryDatabase.new.call(
+  sql: "SELECT schemaname, tablename, seq_scan, seq_tup_read, idx_scan, idx_tup_fetch FROM pg_stat_user_tables ORDER BY seq_scan DESC",
+  limit: 20
+)
+```
+
+High `seq_scan` counts compared to `idx_scan` indicate tables where indexes
+are missing and sequential scans are happening frequently.
+
+## Failure Mode Guide
+
+| Symptom | Likely Cause | Action |
+|---------|-------------|--------|
+| Query takes >1s | Missing index on WHERE column | Check pg_indexes, add index |
+| Same query 50x in log | N+1 in controller/view | Add `.includes()` |
+| Query slow AFTER adding index | Wrong index type or order | Verify index column order matches query |
+| `EXPLAIN ANALYZE` hanging | Table lock or very large table | Use `EXPLAIN (BUFFERS)` without ANALYZE |
+| Missing `pg_indexes` output | Not Postgres | Use `SHOW INDEX FROM <table>` for MySQL |

data/lib/ask/skills/rails.deploy_pipeline/SKILL.md

@@ -0,0 +1,125 @@
+---
+name: rails.deploy_pipeline
+description: Pre-deployment checklist for Rails applications — migrations, assets, credentials, jobs, and logs
+---
+
+Use this skill before or during a Rails deployment to ensure nothing is missed.
+Follow the steps in order — each builds on the previous.
+
+## Step 1: Check Pending Migrations
+
+Before deploying, always check for unapplied migrations:
+
+```ruby
+RunCommand.new.call(command: "bin/rails db:migrate:status | grep 'down'")
+```
+
+If there are pending migrations:
+1. Review them with `ReadFile.new.call(path: "db/migrate/<TIMESTAMP>_migration_name.rb")`
+2. Verify they're reversible: check `change`, `up`/`down`, or `reversible` blocks
+3. Check for data migrations (e.g., backfills) that should run separately
+4. Estimate execution time — large tables may need locking strategy
+
+## Step 2: Verify Assets Pipeline
+
+For Rails with assets (Sprockets or Propshaft):
+
+```ruby
+# Precompile locally to catch errors early
+RunCommand.new.call(command: "bin/rails assets:precompile 2>&1")
+```
+
+Check for:
+- Missing asset references (SCSS variables, image references)
+- JavaScript compilation errors
+- Asset fingerprint changes (manifold fingerprints if CSS changed)
+
+For importmap or esbuild/vite setups:
+
+```ruby
+# Check build config
+ReadFile.new.call(path: "package.json")
+ReadFile.new.call(path: "vite.config.ts") if File.exist?("Rails.root.join('vite.config.ts')")
+```
+
+## Step 3: Review Credentials and Secrets
+
+Verify that all required credentials exist in the target environment:
+
+```ruby
+# For production credentials
+RunCommand.new.call(command: "bin/rails credentials:show --environment production 2>&1")
+```
+
+Check for common secrets that may need updating:
+- `secret_key_base`
+- `database_password`
+- Third-party API keys (AWS, Stripe, SendGrid, etc.)
+- JWT signing keys
+- Any env vars referenced in `config/` files that aren't in credentials
+
+## Step 4: Check Background Jobs
+
+Review sidekiq/active job configuration before deploy:
+
+```ruby
+# Check job files for any that need queue configuration
+Glob.new.call(pattern: "app/jobs/**/*.rb")
+```
+
+For any new or modified jobs:
+1. Verify the queue adapter is configured in `production.rb`
+2. Check for job retry logic that might affect rollback
+3. Review `ReadFile.new.call(path: "config/sidekiq.yml")` if using Sidekiq
+4. Verify scheduled/cron jobs if using `sidekiq-cron` or `whenever`
+
+## Step 5: Review Production Log for Pre-deploy Issues
+
+Check that the current production environment is healthy before deploying:
+
+```ruby
+ReadLog.new.call(lines: 100, level: "ERROR")
+```
+
+If there are recent errors, investigate before deploying more changes.
+
+## Step 6: Verify Dependencies and Gem Versions
+
+Check for critical gem updates or changes:
+
+```ruby
+# Review Gemfile for new/modified gems
+RunCommand.new.call(command: "git diff HEAD -- Gemfile")
+```
+
+If adding a gem that needs system dependencies or native extensions:
+```ruby
+RunCommand.new.call(command: "bundle platform")
+```
+
+## Step 7: Config File Checklist
+
+Verify configuration files for the target environment:
+
+```ruby
+ReadFile.new.call(path: "config/environments/production.rb")
+ReadFile.new.call(path: "config/database.yml")
+ReadFile.new.call(path: "config/cable.yml") if File.exist?("config/cable.yml")
+ReadFile.new.call(path: "config/storage.yml") if File.exist?("config/storage.yml")
+```
+
+Key production checks:
+- `config.force_ssl = true`
+- `config.consider_all_requests_local = false`
+- Proper cache store configured (`:mem_cache_store`, `:redis_cache_store`)
+- Active Storage service configured for production
+
+## Step 8: Quick Rollback Checklist
+
+Before deploying, know how to roll back:
+
+1. **Database**: `RunCommand.new.call(command: "bin/rails db:migrate:down VERSION=<previous>")`
+2. **Code**: Git revert the deploy commit
+3. **Assets**: Previous version's assets should still be cached
+4. **Jobs**: Check if backward-incompatible changes won't replay failed jobs
+5. **Feature flags**: If using flipper or similar, toggle off new features first

data/lib/ask/skills/rails.route_trouble/SKILL.md

@@ -0,0 +1,127 @@
+---
+name: rails.route_trouble
+description: Step-by-step methodology for debugging routing issues in Rails
+---
+
+Use this skill when a route is returning 404, you're getting route matching errors,
+or routes aren't behaving as expected in a Rails application.
+
+## Step 1: Read the Routes File
+
+Start by examining the routes configuration:
+
+```ruby
+ReadRoutes.new.call
+```
+
+This reads `config/routes.rb` — the source of truth for all route definitions.
+
+Look for:
+- The overall structure (namespaced, nested, shallow routes?)
+- Resources that might be missing
+- Constraints or conditions that could block matching
+- Route ordering (more specific routes should come before less specific)
+
+## Step 2: Check the Compiled Routes
+
+Rails routes have a specific matching order. Use `RunCommand` to inspect the live routes:
+
+```ruby
+RunCommand.new.call(command: "bin/rails routes")
+```
+
+If you know the path you're trying to match, grep for it:
+
+```ruby
+RunCommand.new.call(command: "bin/rails routes | grep users")
+```
+
+For a specific route name:
+
+```ruby
+RunCommand.new.call(command: "bin/rails routes --grep user_profile")
+```
+
+## Step 3: Check Route Parameters and Constraints
+
+Routes often fail because of parameter mismatches or constraints. Check for:
+
+**Required parameters:** Does the route define `:id` but the URL doesn't include it?
+
+**Format constraints:** Routes with `:format` (like `.json`, `.html`) constraints
+can fail silently. Check if there's a default format:
+
+```ruby
+# In routes.rb:
+resources :posts, defaults: { format: :json }
+```
+
+**Constraint classes:** Custom route constraints like `subdomain` or request-based
+constraints can prevent matching:
+
+```ruby
+# In routes.rb:
+get "admin", to: "admin/dashboard#show", constraints: ->(req) { req.subdomain == "admin" }
+```
+
+Check the constraints against the actual request parameters.
+
+## Step 4: Trace the Match
+
+For a failing request, trace how Rails would match it:
+
+```ruby
+RunCommand.new.call(
+  command: "bin/rails runner \"puts Rails.application.routes.recognize_path('/users/1/edit', method: :get)\""
+)
+```
+
+This will raise `ActionController::RoutingError` if no route matches — the
+error message tells you what routes were tried before failing.
+
+If the route exists but the controller isn't found:
+
+```ruby
+ReadFile.new.call(path: "app/controllers/users_controller.rb")
+```
+
+## Step 5: Check Namespace and Module Nesting
+
+Routes in namespaced controllers fail when the controller file is in the wrong
+directory or the module is misnamed:
+
+```ruby
+# Route:
+namespace :admin do
+  resources :users
+end
+
+# Expects:
+# app/controllers/admin/users_controller.rb
+# class Admin::UsersController < ApplicationController
+```
+
+Use `Glob` to verify the controller exists:
+
+```ruby
+# Via RunCommand:
+RunCommand.new.call(command: "ls app/controllers/admin/")
+```
+
+## Step 6: Verify Helper Paths and Named Routes
+
+If you're debugging a `No route matches` error from a view (link_to, form_with):
+
+1. Check the route name: `RunCommand.new.call(command: "bin/rails routes | grep user_path")`
+2. Verify the route helper: `RunCommand.new.call(command: "bin/rails routes --grep user")`
+3. Check for route helper overrides in custom constraints or defaults
+
+## Failure Mode Guide
+
+| Symptom | Likely Cause | Action |
+|---------|-------------|--------|
+| 404 for existing route | Route constraint blocking | Check `constraints:` block in routes.rb |
+| `No route matches` | Missing resource definition | Add `resources :model_name` |
+| Route works in dev, not prod | Different route ordering | Check routes file isn't conditionally loaded |
+| `Missing controller` | Wrong namespace or filename | Verify file path matches module structure |
+| Path helper not responding | Wrong route name or params mismatch | Check `bin/rails routes --grep helper_name` |

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ask-rails
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.1
 platform: ruby
 authors:
 - Kaka Ruto
@@ -152,11 +152,17 @@ files:
 - lib/ask/rails/railtie.rb
 - lib/ask/rails/service_discovery.rb
 - lib/ask/rails/tool.rb
+- lib/ask/rails/tools/query_database.rb
 - lib/ask/rails/tools/read_file.rb
+- lib/ask/rails/tools/read_log.rb
+- lib/ask/rails/tools/read_model.rb
 - lib/ask/rails/tools/read_routes.rb
 - lib/ask/rails/tools/run_command.rb
 - lib/ask/rails/tools/search_codebase.rb
 - lib/ask/rails/version.rb
+- lib/ask/skills/rails.db_debug/SKILL.md
+- lib/ask/skills/rails.deploy_pipeline/SKILL.md
+- lib/ask/skills/rails.route_trouble/SKILL.md
 - lib/generators/ask/rails/install/install_generator.rb
 - lib/generators/ask/rails/install/templates/initializer.rb
 - lib/generators/ask/rails/install/templates/migration.rb