Iron Laws

NO unconditional DB queries in mount

Mount runs twice. Default: assign_async. SEO routes: connected? + cache-backed disconnected branch (dead-render IS the crawler-indexed HTML)

ALWAYS use streams for lists >100 items

Regular assigns = O(n) memory per user

CHECK connected?/1 before PubSub subscribe

Prevents double subscriptions

CHECK CHANGESET ERRORS BEFORE UI DEBUGGING

When a form save produces no visible error but no expected side effect, check {:error, changeset} first

NEVER use assign_new for values refreshed every mount

assign_new skips the function if the key exists. Use assign/3 for locale, current user, or any value that must be set on every mount

MATCH {:error, %Ecto.Changeset{}} EXPLICITLY

Bare {:error, _} merges changeset and non-changeset errors; the form never re-renders validation errors. Handle others separately

NEVER use :float for money

Use :decimal or :integer (cents)

ALWAYS pin values with ^ in queries

Never interpolate user input

SEPARATE QUERIES for has_many, JOIN for belongs_to

Avoids row multiplication

NO IMPLICIT CROSS JOINS

from(a in A, b in B) without on: creates Cartesian product

DEDUP BEFORE cast_assoc WITH SHARED DATA

Deduplicate shared child records before building changesets, not inside them

HIDDEN INPUTS FOR ALL REQUIRED EMBEDDED FIELDS

Every required field in an embedded schema MUST have a hidden_input if not directly editable

Jobs MUST be idempotent

Safe to retry

Args use STRING keys, not atoms

Pattern match %{"user_id" => id}

NEVER store structs in args

Store IDs, not %User{}

NO String.to_atom with user input

Atom exhaustion DoS

AUTHORIZE in EVERY LiveView handle_event

Don't trust mount authorization

NEVER use raw/1 with untrusted content

XSS vulnerability

NO process without runtime reason

Processes model concurrency/state/isolation, NOT code structure

SUPERVISE ALL LONG-LIVED PROCESSES

Never bare GenServer.start_link/Agent.start_link in production. Use supervision trees

@external_resource FOR COMPILE-TIME FILES

Modules reading files at compile time MUST declare @external_resource

WRAP THIRD-PARTY LIBRARY APIs

Always facade external dependency APIs behind a project-owned module. Enables swapping libraries without touching callers

MIX TASKS START ONLY WHAT THEY NEED

Mix.Task.run("app.config") + Application.ensure_all_started/1, never Mix.Task.run("app.start") (boots full tree: endpoint port, Oban consuming)

CAPTURE LOCALE BEFORE SPAWNING

Gettext/CLDR locale is process-local. Read it in the caller and pass it explicitly — a spawned Task/GenServer starts with the default locale

VERIFY BEFORE CLAIMING DONE

Never say "should work" or "this fixes it." Run mix compile && mix test and show the result. If you can't verify, explicitly state what remains unverified

COMMENTS AREN'T COMMIT MESSAGES

A change's reasoning belongs in the commit/PR — git persists it, not code. No issue tags inline. Keep only durable facts: footguns, invariants, quirks