rails agents.md

gistfile1.txt

# Contributing to a Rails 8 Application

This document outlines the conventions and best practices for contributing to this Rails 8 application. Adhering to these rules ensures consistency, testability, and a streamlined development process for everyone involved.

## Quick Rules (Read Me First)
- **Task Management**: Before starting, review and update the `CURRENT_TASK.md` file with your current objective. Delete the file when your task is complete.
- **Quality Gates**: Always run the quality suite before committing: `bundle exec rubocop && bundle exec rails test`.
- **Development Environment**: Use `bin/dev` to start all necessary development services, including the Rails server and any background job processors or asset watchers defined in `Procfile.dev`.
- **Logging**: Utilize `Rails.logger.info!`/`debug!`/`warn!`/`error!` for logging. Avoid using `puts` or `p` in application code. Per-request logging should be sufficient for most cases; avoid excessive logging in loops.
- **Architecture**: Prefer "fat models, skinny controllers." Encapsulate complex business logic in Service Objects (`app/services`). Use Active Job for background tasks. Reserve `config/initializers` for global configuration.
- **UI**: Follow RESTful conventions. Use partials and helpers to keep views DRY (Don't Repeat Yourself).
- **Definition of Done**: Your work is done when it compiles cleanly, all automated checks (linter and tests) pass, the feature is manually verified in-app, and no `TODOs` or temporary hacks remain in the code.
- **When Blocked**: Clearly state the problem and propose the next viable step to resolve it.
- **Large-Scale Changes**: Before undertaking significant refactors or new features, propose 2–3 options with their trade-offs. Get team confirmation on the chosen direction before starting.

## 1) Build, Lint, Test (Quality Gates)
A clean and tested codebase is non-negotiable. We enforce this with a simple, combined command:

- **All-in-one quality check**:
  ```fish
  bundle exec rubocop && bundle exec rails test
  ```
- **Linting**: We use RuboCop for static code analysis. Fix all offenses reported by `bundle exec rubocop`. Adhere to the community-driven Ruby on Rails style guide.
- **Testing**: Our test suite is built on Minitest, the Rails default. Run all tests with `bundle exec rails test`.

## 2) Run and Debug (Dev Loop)
A smooth development loop is key to productivity.

- **Starting the App**: Use the `bin/dev` command. This will start all processes defined in `Procfile.dev`, such as the Rails server, a JavaScript/CSS watcher, and a background job worker.
- **Interactive Debugging**: For in-depth debugging, use `binding.irb` (or `binding.pry` if installed) directly in your code. When the application execution hits this line, it will pause and provide you with an interactive console session in the terminal running the `rails server`.
- **Rails Console**: For experimenting with code, querying data, and manually triggering actions, use the Rails console. Start a session with:
  ```fish
  bundle exec rails console
  ```
- **Logging Practices**:
  - Use the appropriate log levels (`debug`, `info`, `warn`, `error`, `fatal`).
  - Avoid noisy, per-request logs inside loops or frequently-called methods.

## 3) Testing Priorities
1.  **Unit Tests**: These should be your first priority. Test models and service objects in isolation. They should be fast and deterministic.
2.  **Integration Tests**: After unit tests, ensure different parts of the application work together correctly. These tests simulate browser requests and user interactions.
3.  **Manual Verification**: Always manually test your feature in a development environment to catch issues not covered by automated tests.
4.  **System Tests**: For critical user flows, system tests that run in a real browser (headless or not) can be used, but they are slower and should be used judiciously.

## 4) Architecture Guardrails
This application follows standard Rails conventions, emphasizing clarity and separation of concerns.

- **MVC (Model-View-Controller)**: This is the core Rails architecture.
    - **Models (`ActiveRecord::Base`)**: Contain data and the business logic directly related to that data (associations, validations, and simple methods).
    - **Controllers (`ActionController::Base`)**: Handle incoming requests, interact with models or service objects, and render views. Keep controllers "skinny."
    - **Views (`ActionView`)**: Responsible for presenting data. Logic in views should be minimal and focused on presentation.
- **Key Principles**:
    - **Service Objects**: For complex business logic that doesn't cleanly fit into a single model, use Plain Old Ruby Objects (POROs) in the `app/services` directory. This keeps both models and controllers lean and focused.
    - **Background Jobs (`ActiveJob`)**: For long-running tasks like sending emails or processing uploads, use ActiveJob to run them asynchronously. This prevents blocking web requests and improves user experience.
    - **Callbacks (`ActiveRecord::Callbacks`)**: Use callbacks for logic that must run at specific points in a model's lifecycle (e.g., `after_create`, `before_save`). Be cautious not to overload them with complex logic; a service object might be a better choice.
    - **Configuration**: Global configuration and initialization code should be placed in `config/initializers`.

## 5) Completion Criteria (Definition of Done)
- All code passes RuboCop with no new offenses.
- The entire test suite (`bundle exec rails test`) passes, including any new or modified tests.
- The feature has been manually verified in a development environment.
- No temporary workarounds or `TODO` comments are left in the production code path.
- The code adheres to the project standards outlined in this document.

## 6) Never-Give-Up Policy
- Do not merge pull requests with failing checks or known regressions.
- Avoid submitting placeholder solutions or hacks as "complete."
- If you are genuinely blocked, document the issue, explain the steps you've taken, and propose a viable path forward for discussion.

## 7) Dev Convenience
- **Custom Rake Tasks**: For repetitive development and administrative tasks, create custom Rake tasks in the `lib/tasks/` directory. You can list all available tasks with `bundle exec rails -T`.
- **Database Seeding**: The `db/seeds.rb` file should be used to populate the development database with necessary initial data. Run it with `bundle exec rails db:seed`.

## 8) Asset Management
- This project uses **Propshaft** as the asset pipeline, which is the default in Rails 8.
- For JavaScript, we use **import maps** by default, which avoids the need for a separate bundling process for simple cases.
- If more complex JavaScript or CSS processing (like transpilation) is needed, the app will use `jsbundling-rails` or `cssbundling-rails`.
- If a full-featured frontend development server is required, we use **Vite Ruby**. In this case, `bin/dev` will also start the Vite dev server.

## 9) Tech Snapshot
- **Ruby on Rails 8**: Check the `.ruby-version` and `Gemfile` for specific versions.
- **Database**: PostgreSQL in production and SQLite in development.
- **Background Jobs**: Solid Queue is the default Active Job backend, using the primary database.
- **Frontend**: Managed via Propshaft and either import maps or Vite.

Keep changes small, tested, and instrumented. When in doubt: write a unit test and verify.

### 10) Design-First for Large Changes
- When to do this: large refactors, cross-crate changes, complex features, public API changes.
- Deliverable (in CURRENT_TASK.md):
- Problem and goals (constraints, assumptions).
- 2–3 candidate approaches with pros/cons, risks, and impact.
- Chosen approach and why; edge cases; test plan; rollout/rollback.
- Keep it short (5–10 bullets). Get confirmation before heavy edits.