narrow-bare-rescue
Narrow bare rescue in Elixir so real errors like KeyError and typos propagate instead of being swallowed. Use to audit rescues and refactor error handling.
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/narrow-bare-rescue
claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
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
Narrow Bare Rescue
Turn rescue _ -> fallback into rescue _ in [ExceptionType1, ExceptionType2] -> fallback
so programmer bugs propagate while known failure modes stay handled.
Why this matters
Bare rescues (rescue _ ->, rescue e -> — any form without an in clause) swallow
every exception, including UndefinedFunctionError from typos, KeyError from
misspelled map keys, and CompileError from bad HEEx templates. The symptom isn't a stack
trace — it's a silent {:error, :generic} or a nil fallback. Bugs that should surface
in tests or error reporters become quiet degradations.
The Erlang Secure Coding Guide makes
the same case at the BEAM level — rule LNG-002 ("Do Not Use catch") warns that the
legacy catch-all form conflates normal returns, throws, and errors. Bare rescue in Elixir
is the direct analogue.
Iron Laws
- Never leave
rescue _ ->orrescue e ->without aninclause. Every rescue must list exact exception types. The Credo check enforces this after cleanup lands. - Cover every exception the code path can actually raise. Narrowing that drops a real exception is a behavioral regression — trace each call in the body before committing.
- Never include programmer-bug exceptions in the list.
UndefinedFunctionError,CompileError,BadFunctionError, andBadArityErrormust propagate. - Use
reraise e, __STACKTRACE__, neverreraise e, []. Preserve the original stack trace so Oban retry metadata and error reporters show the real origin. - Run
mix compile --warnings-as-errorsbefore committing. Typos in exception module names only surface at compile time — the code looks fine until it loads.
The core transform
# Before — masks programmer bugs
def parse(body) do
Jason.decode!(body)
rescue
_ -> %{}
end
# After — catches only what can actually fail here
def parse(body) do
Jason.decode!(body)
rescue
_ in [Jason.DecodeError, ArgumentError] -> %{}
end
Applies identically to try … rescue … and to function-body def … rescue ….
Workflow
The skill operates in three modes depending on scope:
- Single file —
/narrow-bare-rescue path/to/file.ex - Directory —
/narrow-bare-rescue lib/my_app/util/ - Whole project —
/narrow-bare-rescue --all
Whatever the scope, follow this sequence.
Step 1 — Find the sites
grep -rn "^\s*rescue\s*$" <scope> | head -200
For each hit, read the 3 lines after to classify:
rescue _ ->orrescue var ->— bare, needs narrowingrescue _ in [...] ->orrescue var in Something ->— already typed, skiprescue ExceptionType ->(no variable binding) — already typed, skip
Step 2 — Determine the exception set for each bare site
Read the try / def body and trace what each call can raise. Don't guess from the
function name — verify. Consult order:
Check
${CLAUDE_SKILL_DIR}/references/taxonomy.mdfor the work type (JSON, Ecto, Money, HTTP, etc.). Most sites map cleanly to one row.Grep deps for
defexceptionwhen a specific library isn't in the taxonomy:grep -rn "defexception" deps/<libname>/lib/ | head -10Check
raisecalls in the code path itself — if the body explicitly raisesRuntimeError, include it.
Priorities: cover everything the code can actually raise, exclude programmer-bug
exceptions (see Iron Law #3), and prefer specific types (Jason.DecodeError beats
ArgumentError if both could apply).
Step 3 — Apply the narrowing
For files with ≥3 rescues sharing a taxonomy, hoist to a module attribute — see
${CLAUDE_SKILL_DIR}/references/patterns.md for the module-attribute pattern, Oban reraise, ExCmd exit
errors, and is_exception/1 replacements.
Step 4 — Verify
After changes in each file (or cluster of files), run:
mix compile --warnings-as-errors
mix format <files_changed>
mix test <test_files_for_affected_modules>
The compile step catches typos in exception module names — a real risk since you're writing module names from memory.
Scope
This skill narrows bare rescue clauses. It does not:
- Auto-narrow blindly — behavior preservation matters; trace each call path first
- Touch rescues that are already typed (
rescue e in [X] ->) — those are correct - Cover
catchclauses — throws and exits from the process are a separate concern - Replace
try/rescuewithwithor error-tuple plumbing — that's a larger refactor
References
${CLAUDE_SKILL_DIR}/references/taxonomy.md— verified exception types per work category, plus library-specific gotchas (NimbleCSV, Plug, Phoenix LiveView tokenizer)${CLAUDE_SKILL_DIR}/references/patterns.md— special patterns:is_exception/1, Oban reraise, ExCmd exit errors, module-attribute hoisting, partitioning large cleanups, the regression-prevention Credo check- Erlang Secure Coding Guide — LNG-002: Do Not Use
catch— BEAM-level rationale for preferring narrowtry ... catch/try ... rescueover the legacy catch-all form
Files (claude-elixir-phoenix)
-
references
-
patterns.md 3.8 KB
Loading… -
taxonomy.md 10.4 KB
Loading…
-
-
SKILL.md 5.5 KB
--- name: narrow-bare-rescue description: "Narrow bare rescue in Elixir so real errors like KeyError and typos propagate instead of being swallowed. Use to audit rescues and refactor error handling." effort: medium user-invocable: true argument-hint: "[file_path | directory | --all]" paths: - "**/*.ex" - "**/*.exs" --- # Narrow Bare Rescue Turn `rescue _ -> fallback` into `rescue _ in [ExceptionType1, ExceptionType2] -> fallback` so programmer bugs propagate while known failure modes stay handled. ## Why this matters Bare rescues (`rescue _ ->`, `rescue e ->` — any form without an `in` clause) swallow **every** exception, including `UndefinedFunctionError` from typos, `KeyError` from misspelled map keys, and `CompileError` from bad HEEx templates. The symptom isn't a stack trace — it's a silent `{:error, :generic}` or a `nil` fallback. Bugs that should surface in tests or error reporters become quiet degradations. The Erlang [Secure Coding Guide](https://www.erlang.org/doc/system/secure_coding.html) makes the same case at the BEAM level — rule **LNG-002** ("Do Not Use `catch`") warns that the legacy catch-all form conflates normal returns, throws, and errors. Bare `rescue` in Elixir is the direct analogue. ## Iron Laws 1. **Never leave `rescue _ ->` or `rescue e ->` without an `in` clause.** Every rescue must list exact exception types. The Credo check enforces this after cleanup lands. 2. **Cover every exception the code path can actually raise.** Narrowing that drops a real exception is a behavioral regression — trace each call in the body before committing. 3. **Never include programmer-bug exceptions in the list.** `UndefinedFunctionError`, `CompileError`, `BadFunctionError`, and `BadArityError` must propagate. 4. **Use `reraise e, __STACKTRACE__`, never `reraise e, []`.** Preserve the original stack trace so Oban retry metadata and error reporters show the real origin. 5. **Run `mix compile --warnings-as-errors` before committing.** Typos in exception module names only surface at compile time — the code looks fine until it loads. ## The core transform ```elixir # Before — masks programmer bugs def parse(body) do Jason.decode!(body) rescue _ -> %{} end # After — catches only what can actually fail here def parse(body) do Jason.decode!(body) rescue _ in [Jason.DecodeError, ArgumentError] -> %{} end ``` Applies identically to `try … rescue …` and to function-body `def … rescue …`. ## Workflow The skill operates in three modes depending on scope: 1. **Single file** — `/narrow-bare-rescue path/to/file.ex` 2. **Directory** — `/narrow-bare-rescue lib/my_app/util/` 3. **Whole project** — `/narrow-bare-rescue --all` Whatever the scope, follow this sequence. ### Step 1 — Find the sites ```bash grep -rn "^\s*rescue\s*$" <scope> | head -200 ``` For each hit, read the 3 lines after to classify: - `rescue _ ->` or `rescue var ->` — bare, needs narrowing - `rescue _ in [...] ->` or `rescue var in Something ->` — already typed, skip - `rescue ExceptionType ->` (no variable binding) — already typed, skip ### Step 2 — Determine the exception set for each bare site Read the `try` / `def` body and trace what each call can raise. Don't guess from the function name — verify. Consult order: 1. **Check `${CLAUDE_SKILL_DIR}/references/taxonomy.md`** for the work type (JSON, Ecto, Money, HTTP, etc.). Most sites map cleanly to one row. 2. **Grep deps for `defexception`** when a specific library isn't in the taxonomy: ```bash grep -rn "defexception" deps/<libname>/lib/ | head -10 ``` 3. **Check `raise` calls in the code path itself** — if the body explicitly raises `RuntimeError`, include it. Priorities: cover everything the code can actually raise, exclude programmer-bug exceptions (see Iron Law #3), and prefer specific types (`Jason.DecodeError` beats `ArgumentError` if both could apply). ### Step 3 — Apply the narrowing For files with ≥3 rescues sharing a taxonomy, hoist to a module attribute — see `${CLAUDE_SKILL_DIR}/references/patterns.md` for the module-attribute pattern, Oban reraise, ExCmd exit errors, and `is_exception/1` replacements. ### Step 4 — Verify After changes in each file (or cluster of files), run: ```bash mix compile --warnings-as-errors mix format <files_changed> mix test <test_files_for_affected_modules> ``` The compile step catches typos in exception module names — a real risk since you're writing module names from memory. ## Scope This skill narrows bare `rescue` clauses. It does not: - Auto-narrow blindly — behavior preservation matters; trace each call path first - Touch rescues that are already typed (`rescue e in [X] ->`) — those are correct - Cover `catch` clauses — throws and exits from the process are a separate concern - Replace `try/rescue` with `with` or error-tuple plumbing — that's a larger refactor ## References - `${CLAUDE_SKILL_DIR}/references/taxonomy.md` — verified exception types per work category, plus library-specific gotchas (NimbleCSV, Plug, Phoenix LiveView tokenizer) - `${CLAUDE_SKILL_DIR}/references/patterns.md` — special patterns: `is_exception/1`, Oban reraise, ExCmd exit errors, module-attribute hoisting, partitioning large cleanups, the regression-prevention Credo check - [Erlang Secure Coding Guide — LNG-002: Do Not Use `catch`](https://www.erlang.org/doc/system/secure_coding.html) — BEAM-level rationale for preferring narrow `try ... catch` / `try ... rescue` over the legacy catch-all form
Comments (0)
Sign in to join the conversation.
Reviews (0)
No reviews yet.
No comments yet.