Narrow Bare Rescue

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha 492f17636999 · 18 Oct 2026Report an issue or request a re-scan

• Publisheroliver-kriska GitHub userOwner of the repository this skill is read from
• Source folderoliver-kriska/claude-elixir-phoenix/plugins/elixir-phoenix/skills/narrow-bare-rescueThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdict492f17636999A new audit runs when the source changes
• Repository statusNot archivedLast push 2 days ago
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its 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.

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

Excerpt, first 5,520 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/oliver-kriska/claude-elixir-phoenix
git -C claude-elixir-phoenix checkout 492f17636999

Works in

1. 2026-10-18
   ✓SAFE B 89 / 100

   first audit · source 492f17636999

Questions about Narrow Bare Rescue

• github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins — the audited source at commit 492f17636999 and every finding aboveObserved · 18 Oct 2026

Spotted something wrong? Report a correction · Methodology