narrow-bare-rescue
Narrow bare rescue in Elixir so real errors like KeyError and typos propagate
Install
npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/targets/amp/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
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
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
references/taxonomy.md— verified exception types per work category, plus library-specific gotchas (NimbleCSV, Plug, Phoenix LiveView tokenizer)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.3 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. --- # 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 `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 `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 - `references/taxonomy.md` — verified exception types per work category, plus library-specific gotchas (NimbleCSV, Plug, Phoenix LiveView tokenizer) - `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.