---
name: build-elixir
description: >-
  Deliberate TDD-first, design-heavy workflow for building an Elixir/Phoenix
  change end-to-end — surface rival designs, pick one, drive red→green, keep the
  test suite lean. Invoke with: /build-elixir <what you're building>
disable-model-invocation: true
---

# Build Elixir

**Type:** Rigid workflow. Follow the phases in order. This skill routes over other
skills — it names them, it does not restate them. Each phase ends on a checkable
completion criterion; do not advance until it is met.

The spine is the red→green **loop**, entered only *after* a design **gate** the
human owns. Leading words used throughout: **seam** (the interface under change),
**gate** (the human design decision), **red** (the failing test that drives a
cycle), **fold** (collapsing many tests into one).

## Phase 1 — Orient the seam

Read `.claude/rules/domain-architecture.md` and any `CONTEXT.md` for the area, so
your vocabulary matches the project's domain language. Then name, in writing, the
**seam** under change using `/codebase-design` vocabulary: what is the *module*,
what is its *interface* (every fact a caller must know), where does the *seam*
sit, is there a real *adapter* or a hypothetical one.

**Done when:** the seam and its interface are written down and confirmed with the
user.

## Phase 2 — Design gate (mandatory, human-owned)

Run `/design-an-interface` to generate **≥2–3 radically different** designs for the
seam from Phase 1. This gate is never skipped for a non-trivial change, and the
**user makes the final call** — no implementation code is written before the pick.

Surface the designs like this:

1. **Present a comparison table** — one row per design, columns: *design name*,
   *depth* (behaviour hidden behind the interface), *locality* (where change/bugs
   concentrate), *seam placement*, *testability*. Keep each cell to a phrase.
2. **Below the table, one short paragraph per design** — its core idea and the
   single sharpest trade-off (what it buys, what it costs).
3. **Call out a recommended pick first, with one sentence of why** — then present
   the rest neutrally. A recommendation, not a nudge; the reasoning must be visible
   so the user can disagree with it.
4. **Hand the choice over via `AskUserQuestion`** — each design an option, the
   recommended one first labelled `(Recommended)`, each with a `preview` sketching
   its interface. The user may also pick a synthesis or reject all and re-run
   `/design-an-interface` with new constraints.
5. **Hard stop.** Write no implementation code until the user has answered. A clear
   recommendation does not authorize proceeding — the pick is theirs to make.

**Done when:** the user has explicitly picked one design (or a synthesis), and the
chosen seam + interface are restated for the record.

## Phase 3 — Plan (conditional)

Only for **large, multi-surface** features (new context, several LiveViews, a
migration + projection + worker): run `/phx:plan` — it spawns research agents by
feature type, checks Iron Laws, and writes a checkbox plan. For a single-surface
change, **skip this** and go straight to the loop.

**Done when:** either a plan exists, or you've judged the change small enough to
skip and said so.

## Phase 4 — Red→green loop

`/tdd` drives. First agree the **seams under test** with the user (no test at an
unconfirmed seam). Then cycle in vertical slices: one failing test (**red**) →
the minimal code to pass it → repeat, each test a tracer bullet shaped by what the
last cycle taught. Refactoring is **not** part of the loop — it belongs to Phase 6.

**Done when:** the chosen design is implemented and every slice's test is green.

## Phase 5 — Fold the tests

`/exunit-testing`. Keep the suite lean without losing coverage:

- **Fold** near-identical example tests into a single tabular `test` with a
  `for {input, expected} <- @table do` comprehension and a custom failure message.
- Reach for `stream_data` **property tests** on pure functions with invariants
  (Circular / Oracle / Smoke / Invariant patterns) — always paired with 1–3
  example tests pinning known-correct outputs.
- For genuinely per-case named tests, use the `unquote/1` generation variant, or
  Elixir 1.18's native `parameterize:` option on `use ExUnit.Case`.

**Done when:** no cluster of near-duplicate tests remains that a table or property
would express better, and coverage is unchanged.

## Phase 6 — UI branch (only if LiveView/components touched)

The plugin's `liveview-patterns` auto-attaches on `*_live.ex` / `*_component.ex`.
Obey `.claude/rules/liveview.md` (streams for collections, `<.link navigate/patch>`,
`to_form/2` + `<.input>`, no LiveComponents without cause) and
`.claude/rules/frontend.md` (mobile-first, `Theme.typography(:variant)`). Test with
`exunit-testing`'s `liveview-testing.md` conventions (assert on element IDs, never
raw text).

**Done when:** UI tests are green and the LiveView rules are satisfied.

## Phase 7 — Idioms & Iron Laws (adhere, don't restate)

These load automatically — do not copy them into your reasoning, just comply:

- The `inject-iron-laws.sh` hook feeds the Elixir/Phoenix Iron Laws into every
  subagent.
- The plugin's `elixir-idioms`, `ecto-patterns`, `security`, `oban`,
  `phoenix-contexts` auto-attach by context.
- `.claude/rules/elixir-style.md` and `domain-architecture.md` are always loaded
  (generic idioms + the project's DDD modeling idioms live there).

## Phase 8 — Verify

Run `mix precommit` (or `/phx:verify` for a tool-discovering loop). Then a review
pass: `/phx:review` (spawns `iron-law-judge`) for general changes, or
`/review-architecture` for bounded-context / structural changes.

**Done when:** precommit is green and the review pass reports no blockers.

## Rules

- The **gate** (Phase 2) is never skipped for a non-trivial change, and the **user
  picks** the design — never auto-select.
- Never restate the Iron Laws or idioms; name their source and comply.
- Never refactor inside the red→green loop; that is Phase 6/8 work.
- Route to the named skills; do not improvise a manual substitute for `/tdd`,
  `/design-an-interface`, or `exunit-testing` — composing them is the whole point.