In Elixir Essentials

---
description: "Elixir coding rules: pattern matching, tagged tuples, with-railways, @impl true, Highlander"
rules:
  - IN-EX-CODE-001
  - IN-EX-CODE-002
  - IN-EX-CODE-003
  - IN-EX-CODE-004
  - IN-EX-CODE-005
  - IN-EX-CODE-006
---

# Elixir Essentials

Load the Intent Elixir rule pack into context. Invoke at the start of any Elixir coding task or after a context reset.

## Procedure

### 1. Load the production-code rules

Read each rule on demand when the situation matches. The full text of each rule is served by the installed Intent tool via `intent claude rules show <id>`.

| Rule ID          | Slug                              | What it enforces                                           |
| ---------------- | --------------------------------- | ---------------------------------------------------------- |
| `IN-EX-CODE-001` | `pattern-match-over-conditionals` | Multi-clause heads beat nested `if`/`case` on shape.       |
| `IN-EX-CODE-002` | `tagged-tuple-returns`            | `{:ok, v}` / `{:error, r}` instead of bare `nil`.          |
| `IN-EX-CODE-003` | `impl-true-on-callbacks`          | `@impl true` on every behaviour callback.                  |
| `IN-EX-CODE-004` | `with-for-railway`                | Chain fallible operations with `with`, not nested `case`.  |
| `IN-EX-CODE-005` | `no-silent-failures`              | Never `rescue _ -> :ok`; failures are handled or raised.   |
| `IN-EX-CODE-006` | `module-highlander`               | One canonical module per concern; no divergent duplicates. |

Each rule file follows the same shape: `## Problem`, `## Detection`, `## Bad`, `## Good`, `## When This Applies`, `## When This Does Not Apply`, `## Further Reading`. Read the specific rule when you hit the situation it covers.

### 2. Additional operational conventions

These are not yet first-class rules in the library; treat them as mandatory style.

- **Pipe operator for sequential transformations.** Two or more transformations use pipes, first argument is always the data being transformed.
- **Naming conventions.** `?` suffix for booleans (`active?/1`). `!` suffix for raising variants (`fetch!/1`). `_name` for unused args with meaning.
- **Assertive data access.** `struct.field` for required keys (fails fast). `map[:key]` only for genuinely-optional keys. Pattern-match to destructure.
- **No debug artifacts.** Never commit `IO.inspect/2`, `dbg()`, or `IO.puts` for debugging. Use `dbg()` during development; strip before commit.

### 3. Check Usage Rules for framework behaviour

If the task touches a framework, consult the framework's Usage Rules. A framework's rules live at `deps/<dep>/usage-rules.md`, in `deps/<dep>/usage-rules/*.md`, or in both, wherever its package ships them, so look in both places before concluding a dep has none:

- `deps/ash/usage-rules.md`
- `deps/ash_postgres/usage-rules.md`
- `deps/phoenix/usage-rules/liveview.md` -- LiveView's rules ship in Phoenix's package, beside `deps/phoenix/usage-rules/{ecto,elixir,html,phoenix}.md`
- Any other `deps/*/usage-rules.md` or `deps/*/AGENTS.md` relevant to the task
- Topical sub-rules: the `deps/*/usage-rules/*.md` folders a dep ships beside its single file or instead of one (eg `deps/usage_rules/usage-rules/{elixir,otp}.md`). Read these too, not just a top-level `usage-rules.md`.

## Red Flags

| Rationalisation                         | Reality                                                            |
| --------------------------------------- | ------------------------------------------------------------------ |
| "A single `if` is fine here."           | See IN-EX-CODE-001. If the branch is on shape, use multi-clause.   |
| "I'll return `nil` on not-found."       | See IN-EX-CODE-002. Tag failure; callers must see it.              |
| "@impl true is clutter."                | See IN-EX-CODE-003. One typo catches 20 minutes of debugging.      |
| "Nested `case` is clearer than `with`." | See IN-EX-CODE-004. Three-deep pyramid is the Elixir arrow-code.   |
| "I'll just `rescue _ -> :ok` for now."  | See IN-EX-CODE-005. "For now" becomes production's silent failure. |