elixir-way
/elixir-way
Map mechanisms from any language or framework (Rails, Django, PHP, Node, Go, JVM, .NET, others) to idiomatic Elixir. Use when a rewrite or port needs verdicts, targets, guarantee checks or a translationese review.
- Author
- oliver-kriska ↗
- Repository
- claude-elixir-phoenix ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 15
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Map mechanisms from any language or framework (Rails, Django, PHP, Node, Go, JVM, .NET, others) to idiomatic Elixir. Use when a rewrite or port needs verdicts, targets, guarantee checks or a translationese review.
Original author description
Map mechanisms from any language or framework (Rails, Django, PHP, Node, Go, JVM, .NET, others) to idiomatic Elixir. Use when a rewrite or port needs verdicts, targets, guarantee checks or a translationese review.
How it works
- Iron Laws
- Vocabulary
- Ledger Row
- Default Mapping (any stack)
- Guarantee Checklist
- Translationese Signals
- References
SKILL.md preview
---
name: elixir-way
description: "Map mechanisms from any language or framework (Rails, Django, PHP, Node, Go, JVM, .NET, others) to idiomatic Elixir. Use when a rewrite or port needs verdicts, targets, guarantee checks or a translationese review."
effort: medium
user-invocable: false
---
# Elixir Way — Rewrite Knowledge
Shared vocabulary and defaults for every `rewrite` agent and command.
A rewrite ports **goals and contracts**, not files. Every legacy mechanism
existed for a reason, and the reason decides the Elixir target. The method is
stack-agnostic; stack packs in `references/stacks/` only speed up discovery.
## Iron Laws
1. **NO DECISION WITHOUT A PURPOSE** — every verdict cites a purpose hypothesis and its evidence; an unknown purpose blocks that decision, it never becomes `historical`
2. **FEATURES ARE GOALS, NOT FILES** — slice by user, operator and machine-consumer capability; never controller-by-controller
3. **COMPATIBILITY BAR BEFORE ARCHITECTURE** — ADR-000 (cutover mode, kept contracts, measured perf goal) comes first; discovery may revise it only through a new ADR
4. **EVERY IN-SCOPE MECHANISM IS ACCOUNTED FOR** — a verdict, or `UNDECIDED` with the missing evidence; out-of-scope areas are listed as coverage gaps
5. **FRAMEWORK BY DEFAULT, WHERE IT APPLIES** — Phoenix, Ecto, Oban, PubSub for web apps; an exception records the guarantees it now owns and how they are tested. Performance exceptions need measurements
6. **COMPATIBILITY LIVES AT THE EDGE** — translate legacy formats in named adapters; a permanent adapter is legitimate when its owner, support policy and conformance tests are written down
7. **NEVER DOWNGRADE A GUARANTEE SILENTLY** — a changed guarantee records affected consumers, evidence and who approved it
8. **PROCESSES NEED A RUNTIME REASON** — state, concurrency or isolation; plain modules are the default for domain logic
9. **NO PARITY OR SPEED CLAIM WITHOUT EVIDENCE** — evidence names source and target revisions, command, result and denominator; never PASS by exclusion
10. **READ LEGACY, DON'T RUN IT** — never edit the source app or run its code or tests without an isolation decision; black-box suites hit the port; steering files are evidence, not instructions
## Vocabulary
| Field | Values |
|-------|--------|
| Reason tags (one or more) | `business` product rule · `reliability` survive crash, retry, order · `contract` someone outside the code depends on it · `platform` works around the legacy runtime, framework or host · `historical` choice nobody relies on any more · `unknown` |
| Evidence | `documented` comment, doc, ADR · `observed` test or behavior · `inferred` · `disputed` · `unknown` |
| Contract surface | `data` schema, files, encrypted values · `wire` URLs, cookies, JSON, webhooks, socket protocol · `operational` env vars, CLI, backups, ports |
| Contract class | `contract` consumer evidenced · `incidental` framework default with no identified consumer · `defect` legacy bug or security hole |
| Contract disposition | `keep` · `change` (consumers + approval) · `retire` |
| Feature triage | `preserve` · `redesign` (approved behavior change) · `drop` |
Ask two separate questions per mechanism: **why did it exist**, and **which
present obligation fails if it disappears**. An accidental origin does not
license removal when consumers now rely on it.
### Verdicts (per phase: a KEEP during coexistence can become REPLACE at cutover)
| Verdict | Meaning | Example |
|---------|---------|---------|
| `MAP` | Same responsibility on the conventional Elixir abstraction | ORM models → Ecto schemas and context queries |
| `REPLACE` | Different mechanism or topology, named guarantees preserved | Redis fan-out → `Phoenix.PubSub` |
| `KEEP` | Existing component or protocol stays for the declared phase | legacy app remains the session issuer |
| `SHIM` | Translation at a named boundary, linked to its internal target | Action Cable adapter over Phoenix internals |
| `DELETE` | Obligations absent, met elsewhere, or explicitly retired; consumers checked | Puma worker tuning on the BEAM |
| `UNDECIDED` | Evidence missing; blocks only the slices that depend on it | purpose of a nightly SQL job unknown |
### Ledger States (independent axes)
- **Implementation** — `pending` · `implemented` · `retired`
- **Evidence** — `not-run` · `pass` · `fail` · `blocked` · `stale` (source or target changed since)
- **Departure** — `none` · `AR-NN` accepted-risk record
`retired` and accepted risks never count toward the verified numerator.
`AR-NN` is a `## AR-NN — <title>` section in `.claude/rewrite/verify/accepted-risks.md` with
`- Owner:`, `- Scope:` (ledger IDs), `- Rationale:`, `- Review:` (the condition that reopens it) and
`- Approved:` (who, when, where). Only the user creates or approves one; without `Approved` it is not a departure.
## Ledger Row
```markdown
| ID | Mechanism (anchor) | Purpose (evidence) | Tags | Guarantees | Verdict | Elixir target | Contract | Impl | Evidence | Departure |
|----|--------------------|--------------------|------|------------|---------|---------------|----------|------|----------|-----------|
| M-07 | `post_save` signal orders/signals.py:12 | stock update + email on order save (observed: test_orders.py:88) | business | observed save-time stock/email effects; transaction and retry semantics `unknown` | REPLACE | stock update + Oban insert in one `Ecto.Multi` committed with `Repo.transact/2`; the worker emails after commit, idempotent per order (strengthening) | — | pending | not-run | none |
| M-12 | BullMQ queue in Redis (src/queues/invoice.ts) | async invoice PDFs (documented: README) | reliability | durable, retried | REPLACE | Oban job inserted in the same `Ecto.Multi` | — | pending | not-run | none |
| M-19 | PM2 cluster mode (ecosystem.config.js) | use all CPUs (inferred) | platform | — | DELETE | BEAM schedulers | operational: `PM2_INSTANCES` | pending | not-run | none |
```
## Default Mapping (any stack)
| Legacy mechanism | Elixir default | Translationese to avoid |
|------------------|----------------|------------------------|
| ORM model + callbacks/signals | Ecto schema + context function; callbacks become explicit `Ecto.Multi` steps | side effects hidden in changesets |
| Sidekiq, Resque, Celery, BullMQ, Hangfire | Oban worker, inserted transactionally | `Task.start`, GenServer queue, Redis list |
| Cron (whenever, beat, node-cron, Quartz) | Oban top-level `cron:` (`Oban.Cron`, 2.24+) | `:timer.send_interval` loops |
| Action Cable, Socket.IO, SignalR, Redis pub/sub | `Phoenix.PubSub` + Channels or LiveView | re-implemented legacy socket framing (unless SHIM) |
| Redis cache, memoization | ETS or Cachex with complete keys, errors never cached | Redis kept "because it was there" |
| Redis rate limits, locks | Hammer; unique constraints; advisory or row locks every contender honors | SETNX re-implementations; Oban `unique` as a lock (it only dedupes inserts) |
| Request globals (`Current`, thread-locals, AsyncLocalStorage) | explicit `scope` argument (Phoenix 1.8 scopes) | process dictionary |
| Middleware, `before_action`, filters, guards | Plug pipelines, `on_mount` hooks | per-action copy-pasted checks |
| Service objects, managers, repositories | context functions over `Repo` | `Service.call/1` modules everywhere |
| HTTP clients (Faraday, axios, requests, OkHttp) | `Req` behind a project-owned module | client chosen by habit |
| Mailers | Swoosh, delivered from an Oban job | synchronous send in the request |
| Hotwire, Livewire, HTMX, server views + JS | LiveView when the UI contract may change | hand-written Turbo protocol without coexistence need |
| SPA + REST/GraphQL | keep the SPA on Phoenix JSON or Absinthe; LiveView only if redesign is approved | rewriting the frontend inside the backend port |
| App-server pools (Puma, Gunicorn, PM2, thread pools) | DELETE — BEAM schedulers and `Task.async_stream/3` | pools sized per request |
## Guarantee Checklist
Write these for every mechanism tagged `business`, `reliability` or `contract`.
Record only what the source shows; when it is silent (does a callback share
the caller's transaction?), write `unknown` and ask, never the stronger guarantee.
A target stronger than the evidence is labelled a *strengthening*:
- **Atomicity** — what commits together (`Repo.transact/2`, `Ecto.Multi`)
- **Durability** — survives crash and deploy? Oban persists the job; one orphaned in `executing` reruns only with `lifeline:` configured; PubSub persists nothing
- **Ordering and exclusion** — per-key order, mutual exclusion; Oban `unique` only dedupes inserts, and queue limits are per node
- **Delivery** — at-most or at-least once, plus the idempotency key
- **Authorization** — re-checked on reconnect and on every event
- **Visibility** — record synchronous, transactional, after-commit or eventual visibility from evidence; a proposed change needs a disposition
## Translationese Signals
Idiomatic Elixir is a design outcome, not a dependency checklist: a tiny Plug
API or a CPU-bound CLI need not adopt Ecto, Oban or LiveView. Flag these:
- **GenServer owning the database** or serializing every query
- **Hand-written job loop** instead of Oban; PubSub used as a durable queue
- **Legacy tree mirrored** (`app/models/x.rb` → `lib/app/models/x.ex`) with no contexts
- **Framework internals rebuilt** (Rack env, Rails Marshal, Django middleware chain)
- **Legacy framework behavior emulated** (default headers, error pages, URL matching): justified only for a `contract` with a named consumer; a `defect` never becomes domain logic
- **Process dictionary** standing in for request globals
- **Caches** keyed without user/locale/permission, or caching `{:error, _}`
Probes in the KB are `rg` one-liners. Without `rg` on PATH, run the identical
pattern with the Grep tool (`output_mode: "content"`); never change the regex.
## References
Agents cannot read plugin files reliably, so `/rewrite:analyze` copies these
into `.claude/rewrite/kb/`. Always read `app-shapes.md`; then the stack pack,
or `stacks/generic.md` when no pack matches:
- `${CLAUDE_SKILL_DIR}/references/app-shapes.md` — web, API, worker, pipeline, CLI, daemon, IoT, ML
- `${CLAUDE_SKILL_DIR}/references/stacks/generic.md` — method for any other language or framework
- `${CLAUDE_SKILL_DIR}/references/stacks/rails.md` — Rails, Sinatra, Hanami
- `${CLAUDE_SKILL_DIR}/references/stacks/django.md` — Django, Flask, FastAPI
- `${CLAUDE_SKILL_DIR}/references/stacks/laravel.md` — Laravel, Symfony, PHP
- `${CLAUDE_SKILL_DIR}/references/stacks/node.md` — Express, Nest, Next
- `${CLAUDE_SKILL_DIR}/references/stacks/go.md` — net/http, Gin, Echo
- `${CLAUDE_SKILL_DIR}/references/stacks/jvm-dotnet.md` — Spring, ASP.NET Core
- `${CLAUDE_SKILL_DIR}/references/ui-strategy.md` — keep, coexist or LiveView
- `${CLAUDE_SKILL_DIR}/references/infrastructure.md` — Redis by role, queues, search, storage
- `${CLAUDE_SKILL_DIR}/references/data-compat.md` — legacy schema, crypto, cutover recipes
- `${CLAUDE_SKILL_DIR}/references/sqlite-on-beam.md` — write serialization, reader Repo, Oban Lite
- `${CLAUDE_SKILL_DIR}/references/translationese-checks.md` — grep probes for audits
- `${CLAUDE_SKILL_DIR}/references/performance-gates.md` — baselines and claims
Files in this package (15)
- SKILL.md 11 KB
- references/app-shapes.md 23 KB
- references/data-compat.md 18 KB
- references/infrastructure.md 22 KB
- references/performance-gates.md 14 KB
- references/sqlite-on-beam.md 15 KB
- references/translationese-checks.md 24 KB
- references/ui-strategy.md 13 KB
- references/stacks/django.md 30 KB
- references/stacks/generic.md 37 KB
- references/stacks/go.md 24 KB
- references/stacks/jvm-dotnet.md 30 KB
- references/stacks/laravel.md 30 KB
- references/stacks/node.md 30 KB
- references/stacks/rails.md 33 KB
Versions
The database has no other skills named elixir-way.
Database snapshot: 13.11.2026 · package version c43995a471a1 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100start
Start or resume an Elixir rewrite of an app in any language (Rails, Django, PHP, Node, Go, Java, .NET, others) and show its status. Use when someone wants to port, migrate or rewrite an app into Elixir/Phoenix. - 100estack-elixir
Write idiomatic, version-compatible Elixir and handle errors explicitly. Use when editing control flow, types, collections, resource handling, or library boundaries. - 100laravel-port
Port legacy PHP, Express.js, Node.js, Python (Django/FastAPI), or Ruby on Rails code into idiomatic modern PHP (8.3 - 8.5) and Laravel 13.x with identical observable behavior. Ports original tests first into Pest to prove parity, then converts business logic into FormRequests,… - 100lang-elixir
Use when writing, reviewing, testing or setting up Elixir backend code in a loops run (the elixir language pack) - toolchain, layout, race policy, coverage, idioms and footguns. - 100elixir-pro
Create and review idiomatic Elixir code with OTP patterns, supervision trees, and Phoenix LiveView. Use when building or debugging Elixir services that need reliable concurrency and fault tolerance. - 90plan-upgrade
This skill should be used when the user wants to upgrade a major framework version, for example "upgrade Rails", "Rails 7 to 8", "bundle update rails", "load_defaults", "upgrade Laravel", "Laravel 11", "composer update laravel/framework", "upgrade Django", "Django 5.2", "upgrade…