Skip to content

oliver-kriska/claude-elixir-phoenix / targets/pi/skills/phx-learn-from-fix

phx-learn-from-fix

Verified

Capture Elixir/Ecto/LiveView lessons and Hex API rules. Use after corrections or when asked to document learning, record a lesson, prevent a fixed mistake, or remember package guidance with --library.

FileKindSize
SKILL.mdskill md6.9 KB
references/common-mistakes.mdmarkdown5.8 KB

references/common-mistakes.md

View on GitHub
# Common Mistakes - Reference

> **READ-ONLY**: This file ships with the plugin. Do NOT edit it
> at runtime — changes to cached plugin files are lost on update.
> To capture new lessons, use `/skill:phx-learn-from-fix` which writes to
> project CLAUDE.md or auto-memory.

Common Elixir/Phoenix mistakes and their fixes. Use as reference
when checking if a lesson is already documented.

Format:

- **Mistake**: What went wrong
- **Pattern**: Do NOT [bad] - instead [good]
- **Example**: Code showing before/after

---

## Ecto

### String vs Atom Keys

**Mistake**: Using string keys for internal data, atom keys for external

**Pattern**: Do NOT use `map["key"]` for internal structs - instead use `map.key` or pattern match

**Example**:

```elixir
# Bad - external data pattern on internal struct
user["email"]

# Good - atom access for internal data
user.email
%{email: email} = user
```

### Missing Preload

**Mistake**: Accessing association without preloading

**Pattern**: Do NOT access `record.association` without preload - instead use `Repo.preload/2` or include in query

**Example**:

```elixir
# Bad - causes Ecto.Association.NotLoaded
user = Repo.get!(User, id)
user.posts  # Boom!

# Good - explicit preload
user = Repo.get!(User, id) |> Repo.preload(:posts)
user.posts  # Works
```

---

## LiveView

### Blocking Mount

**Mistake**: Slow operations in mount blocking page render

**Pattern**: Do NOT do slow work in mount - instead use `assign_async` or send self a message

**Example**:

```elixir
# Bad - blocks initial render
def mount(_params, _session, socket) do
  data = SlowAPI.fetch()  # User waits...
  {:ok, assign(socket, data: data)}
end

# Good - non-blocking with assign_async
def mount(_params, _session, socket) do
  {:ok, assign_async(socket, :data, fn -> {:ok, %{data: SlowAPI.fetch()}} end)}
end
```

### Missing render_async in Tests

**Mistake**: Testing assign_async without waiting for async completion

**Pattern**: Do NOT assert on async assigns without `render_async/1` - instead call it after `live/2`

**Example**:

```elixir
# Bad - async not completed yet
{:ok, view, _html} = live(conn, ~p"/dashboard")
assert render(view) =~ "Data"  # Fails!

# Good - wait for async
{:ok, view, _html} = live(conn, ~p"/dashboard")
render_async(view)
assert render(view) =~ "Data"  # Works
```

### Trusting LiveView Event Parameters

**Mistake**: Treating `phx-value-*`, form values, or hook payloads as trusted
because the server rendered them

**Pattern**: Do NOT authorize from client-supplied IDs - instead load the
resource and authorize it against the current user and server-side state

**Example**:

```elixir
# Bad - users can change phx-value-id or send the event directly
def handle_event("delete", %{"id" => id}, socket) do
  post = Blog.get_post!(id)
  {:noreply, delete_and_remove(socket, post)}
end

# Good - the ID selects a candidate; scoped server state grants access
def handle_event("delete", %{"id" => id}, socket) do
  with {:ok, post} <- Blog.fetch_post_for_user(socket.assigns.current_user, id),
       :ok <- Blog.authorize(:delete, socket.assigns.current_user, post) do
    {:noreply, delete_and_remove(socket, post)}
  else
    {:error, reason} when reason in [:not_found, :unauthorized] ->
      {:noreply, put_flash(socket, :error, "Post is unavailable")}
  end
end
```

IDs in rendered HTML or event payloads should be treated as public identifiers;
their exposure is not an authorization flaw by itself. Use opaque references
when disclosure is sensitive, but authorize them server-side too. Return a
user-facing error for legitimate stale data or changed permissions. Raising is
appropriate only after establishing an invariant that the normal UI cannot
violate: LiveViews and channels are temporary children, so their crashes are not
restarted and do not count toward supervisor restart intensity.

---

## OTP

### Unnecessary GenServer

**Mistake**: Creating GenServer for stateless computation

**Pattern**: Do NOT use GenServer for code organization - instead use plain modules and functions

**Example**:

```elixir
# Bad - GenServer for stateless work
defmodule MyApp.Calculator do
  use GenServer
  def add(a, b), do: GenServer.call(__MODULE__, {:add, a, b})
  def handle_call({:add, a, b}, _from, state), do: {:reply, a + b, state}
end

# Good - just a function
defmodule MyApp.Calculator do
  def add(a, b), do: a + b
end
```

---

## Testing

### Process.sleep for Timing

**Mistake**: Using Process.sleep to wait for async operations

**Pattern**: Do NOT use `Process.sleep` - instead use `assert_receive` with timeout

**Example**:

```elixir
# Bad - flaky, slow
test "processes message" do
  send_message()
  Process.sleep(100)
  assert processed?()
end

# Good - deterministic
test "processes message" do
  send_message()
  assert_receive {:processed, _}, 1000
end
```

### insert() in Factory Definition

**Mistake**: Using insert() inside factory, creating DB records even on build()

**Pattern**: Do NOT use `insert/1` in factory definitions - instead use `build/1`

**Example**:

```elixir
# Bad - creates user even on build(:post)
def post_factory do
  %Post{author: insert(:user)}
end

# Good - lazy association
def post_factory do
  %Post{author: build(:user)}
end
```

---

## Phoenix

### Business Logic in Controller

**Mistake**: Complex logic in controller actions

**Pattern**: Do NOT put business logic in controllers - instead delegate to context functions

**Example**:

```elixir
# Bad - logic in controller
def create(conn, %{"user" => params}) do
  params = Map.put(params, "role", "member")
  if valid_email?(params["email"]) do
    # 20 more lines...
  end
end

# Good - delegate to context
def create(conn, %{"user" => params}) do
  case Accounts.register_user(params) do
    {:ok, user} -> redirect(conn, to: ~p"/users/#{user}")
    {:error, changeset} -> render(conn, :new, changeset: changeset)
  end
end
```
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall