Apply Code Conventions

Style source of truth: Style and formatting defer to the project's configured linter(s). This skill adds non-style behavior and architecture guidance only. For Hotwire + Tailwind specifics, see apply-stack-conventions.

Quick Reference

HARD-GATE

TESTS GATE IMPLEMENTATION:
When this skill guides new behavior, the tests gate still applies:
PRD → TASKS → TEST (write, run, fail) → IMPLEMENTATION → …
No implementation code before a failing test. See write-tests.

Core Process

When reviewing or refactoring Rails code, follow this sequence:

1. Run linter — Detect config (for example .rubocop.yml or .standard.yml), run the appropriate tool, note absence if none found. Do not invent style rules.
2. Apply area-specific rules — Check path patterns (e.g., models, background jobs, controllers) and apply targeted guidance.
3. Verify tests gate — Confirm failing tests exist before any new behavior; run specs and checkpoints.
4. Enforce structured logging — Ensure all Rails.logger calls use static strings + structured hashes with an event: key, plus backtrace for errors.
5. Enforce comment discipline — Ensure all tags (TODO:, FIXME:) have actionable context (owner, ticket).
6. Chain to specialised skills — Use the Integration table to pull in deeper guidance (security, jobs, specs) as needed.

Sub-Rules

Comments and tagged notes

Comment why, not what. Tagged notes — TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE: — are MANDATORY in these triggers; every tag carries actionable context. Naked tags (# TODO: fix this) fail review.

# BAD — naked tag, no context
# TODO: fix this

# GOOD — TODO with next step + dependency
# TODO(jsmith, JIRA-1234): replace TIER_RATES with DB-backed lookup once billing API v2 is stable.

Structured Logging

MANDATORY SHAPE — every Rails.logger.* call uses exactly two positional arguments.

Rails.logger.<level>(static_string_message, { event: "dot.namespaced", ...domain_fields })

# GOOD — error path with backtrace
rescue StandardError => e
  Rails.logger.error("order.processing_failed", {
    event: "order.processing_failed",
    error: e.message,
    backtrace: e.backtrace.first(5).join("\n")
  })
  raise
end

• 1st arg (string): static string literal.
• 2nd arg (hash): first key is always event:.

Apply by area (path patterns)

RSpec and let_it_be (test-prof)

Only recommend let_it_be if test-prof is already in Gemfile.lock. Otherwise default to let; reach for let! only when lazy evaluation would break the example. Don't introduce test-prof unless asked.

Extended Resources (Progressive Disclosure)

Load these files only when their specific content is needed:

• assets/checklist.md — Use for detailed code review checklists.
• assets/snippets.md — Use for quick code snippets of common patterns.

Output Style

When applying conventions, your output MUST include:

1. Detect → run → defer plan — Before any style claim, show how to detect .rubocop.yml / .standard.yml, run the matching linter, and explicitly state that style/formatting defers to the detected config. If no config exists, say so instead of inventing style rules.
2. Per-path convention artifact — Cover every relevant changed path using the Apply by area table: models, controllers, specs, services, and background jobs/workers. Include concrete Rails-oriented recommendations or examples for each matched area.
3. Tests gate verification — For any new behavior, state the failing spec to write, the command to run first, the expected failure, the minimal implementation step, and the passing rerun. Include a manual confirmation that the spec was red before implementation.
4. RSpec setup assumption — Default to let; use let! only when lazy evaluation would break the example; recommend let_it_be only after confirming test-prof already exists in Gemfile.lock; do not introduce test-prof unless asked.
5. Comments — No what-comments; tagged notes (TODO: / FIXME: / HACK: / NOTE: / OPTIMIZE:) on every assumption, deferred work, or business-rule constant; every tag carries actionable context (owner, ticket id, deadline).
6. Logging — Follow Structured Logging rules: static first arg, hash second arg with event:, and a backtrace line on every error rescue.
7. Language — Must be in English unless explicitly requested otherwise.

Integration