Claude Skill

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.

LLM Mart · 0 points · 2 views 0 listing impressions 0 install-command copies
Download oliver-kriska-claude-elixir-phoenix-plugins_elixir-phoenix_skills_narrow-bare-rescue-9767a82.zip · 8 KB

Install

skills CLI npx skills add https://github.com/oliver-kriska/claude-elixir-phoenix/tree/main/plugins/elixir-phoenix/skills/narrow-bare-rescue
Claude Code claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install oliver-kriska-claude-elixir-phoenix@llmmart
Git 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

  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 ${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:

    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:

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

No comments yet.

Reviews (0)

No reviews yet.