oliver-kriska/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

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

# 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

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:

   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:

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 — BEAM-level rationale for preferring narrow try ... catch / try ... rescue over the legacy catch-all form