Elixir Code Review
Review the changed code and enough surrounding code to understand its callers,
public contract, process ownership, supervision context, and existing tests.
Apply the authority order
- Follow the target repository's established public APIs, tests, architecture,
and intentional conventions.
- Follow official Elixir, Erlang/OTP, Phoenix, Ecto, and dependency
documentation.
- Apply the review statements and rule cards from this skill.
- Use general model knowledge last.
Do not apply Phoenix- or Ecto-specific statements unless the repository uses
that framework. When local architecture intentionally differs from a valid
statement's default, do not report the difference unless the change creates a
concrete risk.
If the repository contains an ELIXIR_REVIEW_EXCEPTIONS.md file, treat the
statement slugs listed there as accepted deviations for that repository and do
not report them.
Perform the review
- Identify the behavior changed by the pull request.
- Read the statements index and select the
statements whose triggers match the changed code. Ignore statements whose
triggers do not appear in the diff or its immediate context.
- Evaluate the changed code against each selected statement. Open the linked
rule card only when a borderline case needs the fuller decision guidance:
- PM001 — pattern matching,
guards, external input, dynamic atoms
- CF001 —
with, case,
cond, if, branching
- FN001 — public
functions, visibility, arities, options, return contracts
- DATA001 — maps, structs,
keyword lists, schemas, changesets
- ERR001 — tagged tuples,
exceptions, error translation, process failure
- OTP001 — GenServer, Task, Agent,
Registry, ETS, supervision, concurrency
- TEST001 — ExUnit, mocks, HTTP
testing, process tests, dependency injection
- OBS001 — telemetry, metrics, tags,
durations, instrumentation, logging
- REV001 — aliasing,
supervision altitude, invariants at the source, config threading,
numeric tunables, unconsumed metrics, spec-doc hygiene, sibling-domain
parity (distilled from recurring human review feedback)
- Use the design principles when
a change crosses several of these concerns.
- Confirm that each suspected violation is reachable and introduced or
materially worsened by the pull request.
- Check whether existing tests, callers, or documented behavior disprove the
suspected violation.
- Report only findings with a concrete correctness, reliability, security,
operability, or maintainability consequence.
- Explain the failure mode and the smallest reasonable correction.
Report findings by statement
Every finding must cite the statement slug it violates (for example
PM001.no-dynamic-atoms). A concern that maps to no statement may still be
reported when it meets the concrete-consequence bar in step 7; mark it
(no-statement) so it can be considered for a future statement.
Severity follows the statement level:
- MUST violation — report as a defect that must be fixed before merge.
- SHOULD deviation — report as a non-blocking suggestion, and only when it
has a concrete consequence in this change.
Do not report the same slug twice for the same root cause; group repeated
instances under one finding with all locations listed.
When the host environment provides a dedicated findings-reporting tool (for
example ReportFindings), report through that tool using the severity
semantics above, and put the statement slug in each finding's category or
summary so it stays visible. Otherwise report the findings as text.
Prioritize high-value findings
- Unsafe handling of untrusted external data or dynamic atom creation.
- Broken or inconsistent public return contracts.
- Expected failures that are swallowed, leaked, or raised unexpectedly.
- Processes without a concrete state, concurrency, lifecycle, isolation, or
fault-recovery requirement.
- Missing restart, state-recovery, timeout, or supervision semantics.
- Race-prone process tests and arbitrary sleeps.
- Tests that mock ordinary internal implementation instead of observable
behavior.
- Missing coverage for newly introduced success, failure, or boundary paths.
- Children started under a supervisor that does not match their scope, and
defensive clauses downstream of an invariant the source should enforce.
- Renamed aliases (
as:) or aliases that hide which of two same-named
domain modules is being called.
- Unjustified numeric tunables and metrics or telemetry with no consumer.
Out of scope: mechanically checkable issues
Do not spend findings on anything the project's standard tooling already
catches deterministically:
- Formatting and layout —
mix format owns these.
- Standard lint findings — Credo owns these (unused variables, module and
function naming, alias ordering, nesting depth,
Enum vs Stream in
pipelines, and any check enabled in the project's .credo.exs).
- Type and spec mismatches Dialyzer reports.
- Security patterns Sobelow flags, unless the change adds a concrete
exploitable path Sobelow's static patterns cannot see.
Exception: dynamic atom creation (PM001.no-dynamic-atoms) stays in scope
even where Credo's UnsafeToAtom check exists, because indirect paths
(interpolated module names, atoms built in helper functions) evade the lint.
Review-tooling files are not code under review. Exclude this skill's own
directory and any agent or review configuration under paths like
.github/skills/ or .claude/ from findings, even when they appear in the
diff.
Do not report formatter issues, subjective style preferences, speculative
rewrites, or an alternative design that is merely equally valid. Do not require
a broad refactor when the changed lines can be corrected locally.
1---2description: Review Elixir, Phoenix, Ecto, and OTP pull requests for concrete correctness, reliability, data-boundary, error-contract, public-API, concurrency, supervision, and testing problems. Use for GitHub Copilot code review or any review containing .ex or .exs changes, especially changes involving external input, tagged tuples, processes, background work, HTTP clients, or ExUnit tests.3name: elixir-code-review4metadata:5 source: https://skillmd.com/skills/dbernazal/elixir-code-review6---78# Elixir Code Review910Review the changed code and enough surrounding code to understand its callers,11public contract, process ownership, supervision context, and existing tests.1213## Apply the authority order14151. Follow the target repository's established public APIs, tests, architecture,16 and intentional conventions.172. Follow official Elixir, Erlang/OTP, Phoenix, Ecto, and dependency18 documentation.193. Apply the review statements and rule cards from this skill.204. Use general model knowledge last.2122Do not apply Phoenix- or Ecto-specific statements unless the repository uses23that framework. When local architecture intentionally differs from a valid24statement's default, do not report the difference unless the change creates a25concrete risk.2627If the repository contains an `ELIXIR_REVIEW_EXCEPTIONS.md` file, treat the28statement slugs listed there as accepted deviations for that repository and do29not report them.3031## Perform the review32331. Identify the behavior changed by the pull request.342. Read [the statements index](references/statements.md) and select the35 statements whose triggers match the changed code. Ignore statements whose36 triggers do not appear in the diff or its immediate context.373. Evaluate the changed code against each selected statement. Open the linked38 rule card only when a borderline case needs the fuller decision guidance:39 - [PM001](references/PM001_pattern_matching_guards.md) — pattern matching,40 guards, external input, dynamic atoms41 - [CF001](references/CF001_control_flow_selection.md) — `with`, `case`,42 `cond`, `if`, branching43 - [FN001](references/FN001_function_design_visibility.md) — public44 functions, visibility, arities, options, return contracts45 - [DATA001](references/DATA001_data_structures.md) — maps, structs,46 keyword lists, schemas, changesets47 - [ERR001](references/ERR001_error_handling.md) — tagged tuples,48 exceptions, error translation, process failure49 - [OTP001](references/OTP001_process_design.md) — GenServer, Task, Agent,50 Registry, ETS, supervision, concurrency51 - [TEST001](references/TEST001_test_architecture.md) — ExUnit, mocks, HTTP52 testing, process tests, dependency injection53 - [OBS001](references/OBS001_observability.md) — telemetry, metrics, tags,54 durations, instrumentation, logging55 - [REV001](references/REV001_recurring_reviewer_themes.md) — aliasing,56 supervision altitude, invariants at the source, config threading,57 numeric tunables, unconsumed metrics, spec-doc hygiene, sibling-domain58 parity (distilled from recurring human review feedback)594. Use [the design principles](references/01_elixir_design_principles.md) when60 a change crosses several of these concerns.615. Confirm that each suspected violation is reachable and introduced or62 materially worsened by the pull request.636. Check whether existing tests, callers, or documented behavior disprove the64 suspected violation.657. Report only findings with a concrete correctness, reliability, security,66 operability, or maintainability consequence.678. Explain the failure mode and the smallest reasonable correction.6869## Report findings by statement7071Every finding must cite the statement slug it violates (for example72`PM001.no-dynamic-atoms`). A concern that maps to no statement may still be73reported when it meets the concrete-consequence bar in step 7; mark it74`(no-statement)` so it can be considered for a future statement.7576Severity follows the statement level:7778- **MUST** violation — report as a defect that must be fixed before merge.79- **SHOULD** deviation — report as a non-blocking suggestion, and only when it80 has a concrete consequence in this change.8182Do not report the same slug twice for the same root cause; group repeated83instances under one finding with all locations listed.8485When the host environment provides a dedicated findings-reporting tool (for86example `ReportFindings`), report through that tool using the severity87semantics above, and put the statement slug in each finding's category or88summary so it stays visible. Otherwise report the findings as text.8990## Prioritize high-value findings9192- Unsafe handling of untrusted external data or dynamic atom creation.93- Broken or inconsistent public return contracts.94- Expected failures that are swallowed, leaked, or raised unexpectedly.95- Processes without a concrete state, concurrency, lifecycle, isolation, or96 fault-recovery requirement.97- Missing restart, state-recovery, timeout, or supervision semantics.98- Race-prone process tests and arbitrary sleeps.99- Tests that mock ordinary internal implementation instead of observable100 behavior.101- Missing coverage for newly introduced success, failure, or boundary paths.102- Children started under a supervisor that does not match their scope, and103 defensive clauses downstream of an invariant the source should enforce.104- Renamed aliases (`as:`) or aliases that hide which of two same-named105 domain modules is being called.106- Unjustified numeric tunables and metrics or telemetry with no consumer.107108## Out of scope: mechanically checkable issues109110Do not spend findings on anything the project's standard tooling already111catches deterministically:112113- Formatting and layout — `mix format` owns these.114- Standard lint findings — Credo owns these (unused variables, module and115 function naming, alias ordering, nesting depth, `Enum` vs `Stream` in116 pipelines, and any check enabled in the project's `.credo.exs`).117- Type and spec mismatches Dialyzer reports.118- Security patterns Sobelow flags, unless the change adds a concrete119 exploitable path Sobelow's static patterns cannot see.120121Exception: dynamic atom creation (`PM001.no-dynamic-atoms`) stays in scope122even where Credo's `UnsafeToAtom` check exists, because indirect paths123(interpolated module names, atoms built in helper functions) evade the lint.124125Review-tooling files are not code under review. Exclude this skill's own126directory and any agent or review configuration under paths like127`.github/skills/` or `.claude/` from findings, even when they appear in the128diff.129130Do not report formatter issues, subjective style preferences, speculative131rewrites, or an alternative design that is merely equally valid. Do not require132a broad refactor when the changed lines can be corrected locally.