Apply Stack Conventions

Quick Reference

HARD-GATE

ALL new code MUST have its test written and validated BEFORE implementation.
  1. Write the spec file content, not only the spec path: bundle exec rspec spec/[path]_spec.rb
  2. Verify it FAILS — output must show the observed failure proving the feature does not exist yet
  3. Write the implementation code
  4. Verify it PASSES — run the same spec and include the observed green result line
  5. Refactor if needed, keeping tests green
The final artifact must show the test proof before implementation code.
For each layer, repeat the same spec command after implementation and show
the GREEN result line, not only an arrow or planned verification.
Use **Observed RED output** and **Observed GREEN output** labels for proof
copied from a run; do not present illustrative comments or "e.g." examples as
verification evidence.
See write-tests for the full gate cycle.

Core Process

When writing or generating code for this project, follow these conventions. Stack: Ruby on Rails, PostgreSQL, Hotwire (Turbo + Stimulus), Tailwind CSS.

Style: If the project uses a linter, treat it as the source of truth for formatting. For cross-cutting design principles (DRY, YAGNI, structured logging, rules by directory), use apply-code-conventions.

Feature Development Workflow

For a typical feature, compose stack patterns in this order:

1. Model — add validations, associations, scopes; eager-load with includes for any association used in loops
2. Service object — extract non-trivial business logic from the controller (see create-service-object)
3. Controller — keep actions thin; delegate to services; respond with turbo_stream and html formats
4. View / Turbo wiring — wrap dynamic sections in <turbo-frame> tags; broadcast turbo_stream responses from the controller
5. Stimulus — add a controller only when client-side interactivity cannot be handled by Turbo alone
6. Tailwind — apply utility classes to the view; extract repeated patterns into partials or Stimulus targets

Each step should remain testable in isolation before wiring to the next layer. In the final artifact, make this explicit in a Layer isolation section: name the focused spec or check for model/query, service, controller/request, view/Turbo, Stimulus, and Tailwind. If a layer is not changed, mark it "not applicable"; do not silently omit view, Stimulus, or Tailwind isolation.

Key Code Patterns

Hotwire: Turbo Frames

<%# Wrap a section to be replaced without a full page reload %>
<turbo-frame id="order-<%= @order.id %>">
  <%= render "orders/details", order: @order %>
</turbo-frame>

<%# Link that targets only this frame %>
<%= link_to "Edit", edit_order_path(@order), data: { turbo_frame: "order-#{@order.id}" } %>

Hotwire: Turbo Streams (broadcast from controller)

respond_to do |format|
  format.turbo_stream do
    render turbo_stream: turbo_stream.replace(
      "order_#{@order.id}",
      partial: "orders/order",
      locals: { order: @order }
    )
  end
  format.html { redirect_to @order }
end

Avoiding N+1 — Eager Loading

# BAD — triggers one query per order
@orders = Order.where(user: current_user)
@orders.each { |o| o.line_items.count }

# GOOD — single JOIN via includes
@orders = Order.includes(:line_items).where(user: current_user)

Service Object (complex business logic out of the controller)

# Controller stays thin — delegate to service
result = Orders::CreateOrder.call(user: current_user, params: order_params)
if result[:success]
  redirect_to result[:order], notice: "Order created"
else
  @order = Order.new(order_params)
  render :new, status: :unprocessable_entity
end

See create-service-object for the full .call pattern and response format.

Security

This project uses Devise for authentication and Pundit for authorization. Apply these on every feature that introduces access-controlled resources.

Pitfalls to Avoid

Output Style

When applying stack conventions, your output MUST include:

1. Stack decisions — State which Rails, PostgreSQL, Hotwire, Stimulus, Tailwind, auth, and service-object conventions apply.
2. Tests-first proof before implementation — Put this section before any implementation code. For each layer, include the actual spec code written or updated, the exact command (bundle exec rspec spec/[path]_spec.rb), and the Observed RED output proving the feature is absent rather than misconfigured. Do not use placeholder or illustrative e.g. failure lines.
3. Layer isolation — Include a dedicated section stating how model/query, service, controller/request, view/Turbo, Stimulus, and Tailwind changes remain independently testable before wiring them together. Name the focused spec/check for each changed layer; mark unchanged layers "not applicable" instead of omitting them.
4. Layered implementation — Separate model/query, service, controller, view, Stimulus, and Tailwind changes when applicable.
5. Performance and security checks — Call out N+1 prevention, authorization policy use, and unsafe params/content handling.
6. Verification — For every layer, repeat the focused spec command after implementation and show the Observed GREEN output result line from that run. Then list Rails specs, system tests, linting, and any browser/manual checks run.
7. Language — Must be in English unless explicitly requested otherwise.

Integration