rails-query-object_skill

Overview

This skill generates Rails query objects following a TDD-first workflow to encapsulate complex database queries, aggregations, and report logic. It guides you to write failing specs, implement query classes in app/queries, and confirm behavior with focused tests. The output enforces multi-tenant isolation, chainable relations, and clear return types for predictable use in controllers and presenters.

How this skill works

The skill creates a spec scaffold in spec/queries to drive development RED->GREEN. It generates query object templates that accept context via the constructor (user:, account:), provide a call method (or named aggregation methods), and return either ActiveRecord::Relation for chainability or Hash for aggregated results. It also embeds patterns for filtering, grouping, and aggregation and reminds you to scope queries to the account for multi-tenant safety.

When to use it

• Encapsulating complex query logic outside models or controllers
• Building dashboards, reports, or aggregated statistics
• Implementing multi-tenant queries that must be scoped to an account
• When you want TDD-driven query development (specs first)
• To return chainable relations for further scoping or present aggregated hashes

Best practices

• Write the spec first in spec/queries and confirm RED before implementing
• Always accept context via constructor (account: or user:) and test isolation
• Return ActiveRecord::Relation when you want chainability; use Hash for aggregations
• Name methods clearly (call for primary operation, descriptive names for aggregations)
• Use includes/joins to avoid N+1 and document @return types in the class

Example use cases

• StaleLeadsQuery that returns an ActiveRecord::Relation of stale leads for the current account
• DashboardStatsQuery that exposes upcoming_events, pending_commissions_total, top_vendors, and leads_by_status
• LeadsByStatusQuery that groups leads into a Hash keyed by status for controller views
• A report query that sums values and returns a Hash of aggregated metrics scoped to account