Narrow Bare Rescue

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 _ -> or rescue e -> without an in clause. 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, and BadArityError must propagate.

• Use reraise e, __STACKTRACE__, never reraise e, []. Preserve the original stack

trace so Oban retry metadata and error reporters show the real origin.

• 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

# 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 _ -> 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:

• Check references/taxonomy.md for the work type (JSON, Ecto, Money, HTTP, etc.).

Most sites map cleanly to one row.

• Grep deps for defexception when a specific library isn't in the taxonomy:

   grep -rn "defexception" deps/<libname>/lib/ | head -10

• 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:

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

— BEAM-level rationale for preferring narrow try ... catch / try ... rescue over

the legacy catch-all form