Claude Skill

learn-from-fix

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.

LLM Mart · 0 points · 0 views 0 listing impressions 0 install-command copies
Virus-scanned Reviewed automatically before listing.

Full trust report

Download oliver-kriska-claude-elixir-phoenix-plugins_elixir-phoenix_skills_learn-from-fix-9767a82.zip · 5 KB
oliver-kriska/claude-elixir-phoenix 560 44 forks MIT Updated 2d ago
Part of oliver-kriska/claude-elixir-phoenix — 93 skills

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/learn-from-fix
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git git clone https://github.com/oliver-kriska/claude-elixir-phoenix.git

The skills CLI installs just this skill, for any of its supported agents. Claude Code installs the whole oliver-kriska/claude-elixir-phoenix collection as a plugin from our marketplace. Git is the plain clone.

Skill manifest

Learn From Fix

After fixing a bug or receiving a correction, capture the lesson to prevent future mistakes.

Usage

/phx:learn-from-fix Fixed N+1 query in user listing - was missing preload
/phx:learn-from-fix String vs atom key mismatch in params handling
/phx:learn-from-fix LiveView assign_async needs render_async in tests
/phx:learn-from-fix --library ical --scope personal ICal.to_ics output needs CRLF line endings
/phx:learn-from-fix --library ical --scope project Use method: "PUBLISH" for calendar feeds

Workflow

Step 1: Verify the Lesson

Persist only one of:

  • A completed fix verified by tests, reproduction, or user confirmation
  • An explicit rule the user taught or asked to save

Stop without writing if neither condition is met. Do not save a hypothesis, unverified workaround, investigation narrative, or unsolved error. Use /phx:compound for a detailed completed investigation. Capture the root cause as a concise actionable rule, not the symptom.

Step 2: Select the Route

When both --library <package> and --scope personal|project are present, use the Library Route. Require both flags; do not guess scope. For the skill directory only, trim surrounding whitespace and lowercase the package name. Preserve underscores when forming directory names (phoenix_live_view becomes hex-phoenix_live_view). Validate the normalized name against ^[a-z][a-z0-9_]+$. If it does not match, ask for a valid Hex package identifier instead of replacing characters or inventing a name. Use the trimmed original identifier, not the normalized directory name, to look up mix.lock.

Without --library, use the General Correction Route.

Step 3: Check Existing Knowledge

Check if already documented:

  • Grep project CLAUDE.md and ~/.claude/CLAUDE.md for the pattern keyword
  • Check auto-memory files for similar lessons
  • For library lessons, inspect both ~/.claude/skills/hex-<package>/SKILL.md and .claude/skills/hex-<package>/SKILL.md
  • Read ${CLAUDE_SKILL_DIR}/references/common-mistakes.md (read-only plugin reference)

Do not duplicate the same lesson across CLAUDE.md, memory, and a package skill. If the same rule exists, merge wording or report it as already captured.

Library Route

Plugin files are read-only: files under ~/.claude/plugins/ are cached and get overwritten on updates. Package skills are user-owned files, never plugin cache files.

Resolve Scope and Precedence

--scope Canonical destination
personal ~/.claude/skills/hex-<package>/SKILL.md
project .claude/skills/hex-<package>/SKILL.md

Personal skills override same-named project skills. If a personal hex-<package> skill exists, never unknowingly create or update a shadowed project skill: explain the conflict and ask whether to update personal scope or keep distinct project-only knowledge. If project scope already exists before a personal write, warn that the new skill will shadow it and offer to merge or move it. Maintain one canonical skill per package unless the user explicitly needs distinct scope-specific rules; never create one skill per lesson.

Read the Locked Version

Inspect mix.lock for the package. Record the exact locked version when found. If it is absent, say the lesson is not tied to a locally locked version and do not invent one. Qualify version-sensitive rules. When two verified rules conflict across versions, preserve both with explicit version ranges instead of replacing either.

Create or Safely Update the Skill

For a new package skill, create:

---
name: hex-<package>
description: <Package/module/API/task trigger terms for this knowledge>
user-invocable: false
---

# <Package> Knowledge

## Verified Rules

- **<Rule>** (verified with <package> <version>): <actionable guidance>

Make the description precise: include the Hex package, Elixir module names, important APIs/file formats, and tasks that should trigger this knowledge. Activation is model-selected from this description; package presence in mix.lock does not guarantee activation.

Before updating an existing skill, read all of it. Preserve unrelated and hand-authored sections. Merge semantically identical rules. If safe merging is unclear, show the conflict and ask instead of overwriting content.

Do not add paths: to a personal package skill by default: it is a file-path activation gate, not a dependency predicate. Add paths: only to project scope when explicitly appropriate and meaningful package-specific paths exist.

General Correction Route

Choose the narrowest non-library destination:

Scope Write to Example
This project Project CLAUDE.md "Never use raw SQL in this app"
This project across sessions Project-keyed auto-memory "jsonb uses string keys"
All your projects ~/.claude/CLAUDE.md personal instructions "Prefer explicit error tuples"
Detailed completed fix .claude/solutions/ via /phx:compound Debugging narrative

For project or personal instructions, preserve existing content and append **RULE NAME** — Do NOT [bad]. Instead [good] under the relevant category. Use personal instructions only for rules that should load in every project. For auto-memory, append to the project-keyed ~/.claude/projects/{project-hash}/memory/MEMORY.md:

### Lesson: [Title]
- **Pattern**: Do NOT [bad] — instead [good]
- **Why**: [root cause explanation]

If the lesson is universal to the plugin rather than one project or package, suggest a plugin contribution; never write it into cached plugin files.

Output

After capturing, confirm:

Lesson captured in [location]

Pattern: Do NOT [bad pattern] — instead [good pattern]
Category: [Ecto/LiveView/OTP/Testing/etc]
Version: [locked package version, not found, or not applicable]

For package skills, also state that description-based activation is model-selected, not guaranteed by mix.lock.

Iron Laws

  1. NEVER write generated knowledge to plugin cache — use only the user-owned destinations above
  2. DO NOT duplicate existing lessons — always check CLAUDE.md and memory before writing
  3. NEVER overwrite hand-authored content — read both package skill scopes and merge safely
  4. ONLY persist verified knowledge — completed fixes or explicit user-taught rules, never hypotheses
  5. DISCLOSE scope precedence — a global package skill shadows its project counterpart

References (READ-ONLY — do NOT edit)

  • ${CLAUDE_SKILL_DIR}/references/common-mistakes.md — Common Elixir mistakes reference. Consult when checking for duplicates.
Files (claude-elixir-phoenix)
  • references
    • common-mistakes.md 5.8 KB 
      # 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 `/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
```
  • SKILL.md 6.9 KB 
    ---
name: learn-from-fix
description: 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.
effort: low
argument-hint: "[--library <hex-package> --scope personal|project] <lesson>"
---

# Learn From Fix

After fixing a bug or receiving a correction, capture the lesson
to prevent future mistakes.

## Usage

```
/phx:learn-from-fix Fixed N+1 query in user listing - was missing preload
/phx:learn-from-fix String vs atom key mismatch in params handling
/phx:learn-from-fix LiveView assign_async needs render_async in tests
/phx:learn-from-fix --library ical --scope personal ICal.to_ics output needs CRLF line endings
/phx:learn-from-fix --library ical --scope project Use method: "PUBLISH" for calendar feeds
```

## Workflow

### Step 1: Verify the Lesson

Persist only one of:

- A completed fix verified by tests, reproduction, or user confirmation
- An explicit rule the user taught or asked to save

Stop without writing if neither condition is met.
Do not save a hypothesis, unverified workaround, investigation narrative, or
unsolved error. Use `/phx:compound` for a detailed completed investigation.
Capture the root cause as a concise actionable rule, not the symptom.

### Step 2: Select the Route

When both `--library <package>` and `--scope personal|project` are present,
use the [Library Route](#library-route). Require both flags; do not guess scope.
For the skill directory only, trim surrounding whitespace and lowercase the
package name. Preserve underscores when forming directory names
(`phoenix_live_view` becomes `hex-phoenix_live_view`).
Validate the normalized name against `^[a-z][a-z0-9_]+$`. If it does not match,
ask for a valid Hex package identifier instead of replacing characters or
inventing a name. Use the trimmed original identifier, not the normalized
directory name, to look up `mix.lock`.

Without `--library`, use the [General Correction Route](#general-correction-route).

### Step 3: Check Existing Knowledge

Check if already documented:

- Grep project CLAUDE.md and `~/.claude/CLAUDE.md` for the pattern keyword
- Check auto-memory files for similar lessons
- For library lessons, inspect both
  `~/.claude/skills/hex-<package>/SKILL.md` and
  `.claude/skills/hex-<package>/SKILL.md`
- Read `${CLAUDE_SKILL_DIR}/references/common-mistakes.md` (read-only plugin
  reference)

Do not duplicate the same lesson across CLAUDE.md, memory, and a package skill.
If the same rule exists, merge wording or report it as already captured.

## Library Route

Plugin files are read-only: files under `~/.claude/plugins/` are cached
and get overwritten on updates. Package skills are user-owned files, never
plugin cache files.

### Resolve Scope and Precedence

| `--scope` | Canonical destination |
|-----------|-----------------------|
| `personal` | `~/.claude/skills/hex-<package>/SKILL.md` |
| `project` | `.claude/skills/hex-<package>/SKILL.md` |

Personal skills override same-named project skills. If a personal
`hex-<package>` skill exists, never unknowingly create or update a shadowed
project skill: explain the conflict and ask whether to update personal scope or
keep distinct project-only knowledge. If project scope already exists before a
personal write, warn that the new skill will shadow it and offer to merge or
move it. Maintain one canonical skill per package unless the user explicitly
needs distinct scope-specific rules; never create one skill per lesson.

### Read the Locked Version

Inspect `mix.lock` for the package. Record the exact locked version when found.
If it is absent, say the lesson is not tied to a locally locked version and do
not invent one. Qualify version-sensitive rules. When two verified rules
conflict across versions, preserve both with explicit version ranges instead of
replacing either.

### Create or Safely Update the Skill

For a new package skill, create:

```markdown
---
name: hex-<package>
description: <Package/module/API/task trigger terms for this knowledge>
user-invocable: false
---

# <Package> Knowledge

## Verified Rules

- **<Rule>** (verified with <package> <version>): <actionable guidance>
```

Make the description precise: include the Hex package, Elixir module names,
important APIs/file formats, and tasks that should trigger this knowledge.
Activation is model-selected from this description; package presence in
`mix.lock` does not guarantee activation.

Before updating an existing skill, read all of it. Preserve unrelated and
hand-authored sections. Merge semantically identical rules. If safe merging is
unclear, show the conflict and ask instead of overwriting content.

Do not add `paths:` to a personal package skill by default: it is a file-path
activation gate, not a dependency predicate. Add `paths:` only to project scope
when explicitly appropriate and meaningful package-specific paths exist.

## General Correction Route

Choose the narrowest non-library destination:

| Scope | Write to | Example |
|-------|----------|---------|
| This project | Project CLAUDE.md | "Never use raw SQL in this app" |
| This project across sessions | Project-keyed auto-memory | "jsonb uses string keys" |
| All your projects | `~/.claude/CLAUDE.md` personal instructions | "Prefer explicit error tuples" |
| Detailed completed fix | `.claude/solutions/` via `/phx:compound` | Debugging narrative |

For project or personal instructions, preserve existing content and append
`**RULE NAME** — Do NOT [bad]. Instead [good]` under the relevant category. Use
personal instructions only for rules that should load in every project. For
auto-memory, append to the project-keyed
`~/.claude/projects/{project-hash}/memory/MEMORY.md`:

```markdown
### Lesson: [Title]
- **Pattern**: Do NOT [bad] — instead [good]
- **Why**: [root cause explanation]
```

If the lesson is universal to the plugin rather than one project or package,
suggest a plugin contribution; never write it into cached plugin files.

## Output

After capturing, confirm:

```text
Lesson captured in [location]

Pattern: Do NOT [bad pattern] — instead [good pattern]
Category: [Ecto/LiveView/OTP/Testing/etc]
Version: [locked package version, not found, or not applicable]
```

For package skills, also state that description-based activation is
model-selected, not guaranteed by `mix.lock`.

## Iron Laws

1. **NEVER write generated knowledge to plugin cache** — use only the user-owned destinations above
2. **DO NOT duplicate existing lessons** — always check CLAUDE.md and memory before writing
3. **NEVER overwrite hand-authored content** — read both package skill scopes and merge safely
4. **ONLY persist verified knowledge** — completed fixes or explicit user-taught rules, never hypotheses
5. **DISCLOSE scope precedence** — a global package skill shadows its project counterpart

## References (READ-ONLY — do NOT edit)

- `${CLAUDE_SKILL_DIR}/references/common-mistakes.md` — Common Elixir mistakes
  reference. Consult when checking for duplicates.

Comments (0)

Sign in to join the conversation.

No comments yet.

Reviews (0)

No reviews yet.

Related

Claude Prompt
Tighten-my-prose editing prompt
Claude Skill
Adversarial code-review skill for Claude
Claude Workflow
Deep-research workflow (fan-out + verify)
Claude Skill
Conventional-commit writer for Claude