| name | gleam-review |
| description | Review Gleam code against the official Gleam conventions, patterns, and anti-patterns guide. Identifies anti-patterns (check-then-assert, catch-all matches, panicking in libraries, abbreviations, fragmented modules), convention violations (unqualified imports, missing type annotations, fallible functions that don't return Result), and opportunities to apply recommended patterns (descriptive errors, invalid-states-impossible modelling, builder pattern). Manual invocation only — run via /gleam-review, optionally with files, directories, or package names as arguments. |
| disable-model-invocation | true |
Gleam Code Review
Review Gleam code against the official Gleam style guide. The full guide is in
references/conventions.md — read it in its entirety before reviewing, every
time. It is the authority for this review; do not substitute general
functional-programming intuitions for what it actually says.
This is a review, not a refactor: report findings and stop. Only apply fixes
if the user asks for them afterward.
Determine scope
Use the first of these that applies:
- Arguments were given (file paths, directories, or package names) — review
those. A bare name like
lattice_core means that package's src/ and
test/ directories.
- There are uncommitted changes — review the changed
.gleam files
(git status / git diff).
- The current branch differs from
main — review the .gleam files changed
on the branch (git diff main...HEAD --name-only).
- Otherwise, ask the user what to review.
Read each in-scope file completely, not just the changed hunks. Most findings
in this guide (fragmented modules, error-type design, catch-all matches) only
make sense with the whole module in view, and a diff-only reading produces
false positives — e.g. flagging a "missing" annotation that is actually
present two lines above the hunk.
How to classify findings
The guide defines three tiers, and the report must keep them distinct because
they carry different weight:
- Conventions and anti-patterns are always-rules. Deviations are
violations — report every one you find.
- Patterns (descriptive errors, invalid-states-impossible, builder,
sans-io, etc.) are judgment calls. Report a pattern only as a suggestion,
and only where applying it would clearly improve the specific code at hand.
A missing pattern is not a violation.
Judgment notes that prevent false positives:
- Formatting is
gleam format's job. Never report layout, line length, or
indentation.
let assert and panics are forbidden in library src/ code, but are
acceptable in test/ code (a failed assertion failing the test is the
point) and at the top level of application code.- A catch-all
_ pattern over an open-ended type (Int, String, lists) is
often unavoidable; the anti-pattern is catch-alls over custom types with a
small closed set of variants, where exhaustive matching was possible.
- Short variable names are abbreviations only if they abbreviate something: a
generic
a in a generic function, or an idiomatic accumulator in a
one-line fold, is not in the same class as cnt, cfg, or proc_dat.
- Before flagging fragmented modules or namespace issues, look at the actual
package layout — module-boundary findings need the directory structure as
evidence, not just one file's imports.
When unsure whether something violates the guide, re-read the relevant
section of references/conventions.md and quote it in the finding. If it is
still genuinely ambiguous, leave it out — a review full of maybes buries the
real findings.
The guide is the charter, but do not stay silent about clearly broken code
you happen to read while reviewing: code that won't compile, corrupts data
(e.g. building JSON by string concatenation without escaping), or crashes on
ordinary input. Flag these in a short "Out of scope, but notable" section —
one or two lines each, no deep bug-hunting. This is a courtesy flag for
things you tripped over, not a second review dimension; if the user wants a
correctness review, that is a different task.
Report format
Lead with a one-paragraph verdict: overall state of the code and the most
important finding. Then:
## Violations
<!-- Conventions broken + anti-patterns present. Omit section if none. -->
- `path/file.gleam:12` — **<Guide section name>**: what the code does, why
the guide forbids it, and what to do instead (with a short code sketch
when the fix isn't obvious).
## Suggestions
<!-- Patterns worth applying + borderline judgment calls. Omit if none. -->
- `path/file.gleam:40` — **<Pattern name>**: what would improve and why it
is worth it here.
## Out of scope, but notable
<!-- Obvious correctness bugs tripped over while reading: won't compile,
data corruption, crashes. One or two lines each. Omit if none. -->
## Notable
<!-- 1-3 things the code does well, only if genuinely notable. -->
Order findings by importance, not file order. Name each finding after the
guide section it comes from (e.g. Check-then-assert, Match all
variants) so the user can look it up. Every finding needs a file:line
reference. If the code is clean, say so plainly — do not manufacture findings
to make the review look thorough.
