Review Architecture

Quick Reference

HARD-GATE

DO NOT list findings that do not survive code-level confirmation.
Verify each High-severity finding by reading the actual code to confirm it is a real structural problem.
If verification reveals it is not genuine, downgrade it or remove it entirely.
If no source files were provided or read, do not invent High findings. Return an
architecture review checklist or assumptions block instead, and say code-level
confirmation is required before reporting findings.
SECRET SAFETY: code-level evidence must never reproduce secrets, tokens, API
keys, passwords, private keys, session cookies, or credential values. If a file
contains a hard-coded secret, report only the file/path, symbol name, credential
type, and a redacted fingerprint such as `[REDACTED_API_KEY]`; do not quote the
literal value.

Core Process

Use this skill when the task is to review or improve the structure of a Rails application or library.

Core principle: Prioritize boundary problems over style. Prefer simple objects and explicit flow over hidden behavior.

Review Order

1. Identify the main entry points: controllers, jobs, models, services.
2. Check where domain logic lives.
3. Inspect model responsibilities, callbacks, and associations.
4. Inspect controller size and orchestration.
5. Read every concern, helper, and presenter: does it do one coherent thing, or does it mix auditing + notifications + emails + external API calls? Mixed concerns are High or Medium severity depending on blast radius. Treat any concern used by only one class as a candidate for deletion — inline it instead.
6. Check whether abstractions clarify the design or only move code around.
7. Verify each High-severity finding by reading the actual code — confirm it is a real structural problem, not just a pattern match on file size or line count. Redact any credential-like values found during verification.

Severity Levels

High-Severity Findings

• Business logic hidden in callbacks or broad concerns
• Controllers orchestrating multi-step domain workflows inline
• Models coupled directly to HTTP, jobs, mailers, or external APIs
• Abstractions that add indirection without a clear responsibility
• Cross-layer constant reach that makes code hard to change

Medium-Severity Findings

• Duplicated workflow logic across controllers or jobs
• Scopes or class methods carrying too much query or policy logic
• Helpers or presenters leaking domain behavior
• Service objects wrapping trivial one-liners
• Concerns combining unrelated responsibilities — check EVERY concern in the app

High-severity callback example:

# Bad — hidden side effects on every save
module Auditable
  included do
    after_create :log_creation
  end
  def log_creation
    AuditLog.create!(...)
    Slack.notify(...)                          # external API in callback
    UserMailer.admin_alert(...).deliver_later  # mailer in callback
  end
end

Fix: keep only AuditLog.create! in the callback; move Slack/mailer to an explicit service call at the call site.

Pitfalls

Extended Resources

• EXAMPLES.md

Output Style

1. Scope: State that the task is an architecture/structure review, not style review, and identify the Rails entry points inspected.
2. Order: Begin with entry points. Then write findings ordered by review area.
3. Boundary-first lens: Prioritize where domain logic lives, whether flow is explicit, and whether abstractions clarify the design or only move code around.
4. Finding Structure: Every finding uses a four-field structure:

   **Severity:** High
   **Affected file:** app/controllers/orders_controller.rb — OrdersController#create
   **Risk:** Controller runs a 5-step domain workflow. Partial state on failure; untestable without HTTP.
   **Improvement:** Extract to Orders::CreateOrder.call(params). Controller handles response/redirect only.

5. High-severity verification: For every High finding, state the concrete code-level evidence read, but redact any secret-like literal before writing the finding. Use evidence like app/services/payments/client.rb references ENV["PAYMENT_API_KEY"] inside a model callback; never quote the actual key, token, password, cookie, private key, or credential value. If code-level confirmation is missing, downgrade or remove the finding. Never use representative file paths or fabricated line numbers as evidence.
6. Completeness: For each finding include severity, affected files or area, why the structure is risky, and the smallest credible improvement. Then list open assumptions and recommended next refactor steps.
7. Language: Must be in English unless explicitly requested otherwise.

Integration