Effect-native capability audit

Sweep the codebase on four axes for code that isn't Effect-native — three static (non-native code that is present) and one dynamic (native code misused):

• Substitution (verbs) — logic that re-implements what Effect already ships: a retry loop that is Schedule, manual env parsing that is Config, custom equality that is Equal/Data, a list helper already in Array. Where did we hand-roll a helper?
• Structural (wiring) — code whose construction / dependency-injection / error / resource spine is still imperative OOP even though the leaves return Effect: a new-able class doing DI (ZulipHttp), a throw inside an Effect-returning method, a dependency threaded as a config field instead of declared in R, a try/finally that wants acquireRelease. Effect used inside functions ≠ an Effect-native program. The substitution axis is blind here — no module's export inventory is named "don't write a class that does DI".
• Modelling (nouns) — data and state whose type throws away a guarantee an Effect data type would give for free: T | null that wants Option, a sentinel or pure throw that wants Either, booleans + optional fields that want a Data.taggedEnum (make illegal states unrepresentable), a bare string id that wants a branded type, in-place array mutation that wants an immutable build, hand-rolled equality that wants Equal/Data, a data-first helper that blocks clean pipe composition. The dishonesty is in the representation, not in a missing call or an imperative spine — so the substitution and structural axes walk past it.
• Behaviour (dynamics) — native-but-misused or policy code: how effects run, fail, and what they trust. Independent effects run sequentially that could be Effect.all-concurrent, an unbounded fan-out onto a shared service (the Zulip rate-limit hazard), a bare Effect.fork whose fiber leaks, untrusted data crossing the edge via as/JSON.parse with no Schema decode, an E channel typed Error/unknown or a catchAll that swallows a recoverable failure. The construct is already Effect-native — the smell is the policy. Each finder anchors on present code, not blanket absence ("no timeout anywhere").

This is the structural, modelling & behaviour complement to @effect/language-service. The LSP (~60 rules, enforced at tsc time via bun run check) owns per-line idiom: floating Effects, unnecessary Effect.gen, Effect.void, global fetch/Date/console. It is blind to "this whole 40-line block is a combinator that exists," "this whole module is shaped like an OOP service," "this type lets the caller forget the absent case," and "this fan-out is unbounded." Those blind spots are what this skill covers. Never re-report what the LSP already catches.

How it works

A Workflow script (effect-native-audit.workflow.js) fans out four kinds of finder (see domains.md), all grounded in local clones: Effect source at ~/Development/references/effect and Effect docs at ~/Development/references/effect-website (GitHub-raw / WebFetch fallback when absent).

Substitution finders (~23, one per Effect domain) work inventory-first:

1. List the module's complete export inventory from source — you cannot recognise a copy of Array.partition unless the whole Array surface is in your head.
2. Read the module's docs section for the when & why — the whole section, not just the intro page (Stream is six pages). API-reference-only modules (Array, Record, …) have no prose page and lean on source.
3. Scan our source files for logic that re-expresses a helper in that inventory.

Structural finders (~6, one per smell in the anti-pattern catalogue) work smell-first: read the Effect design docs (services, expected-errors, scope, running-effects, the-effect-type) for why the native shape wins and when the imperative shape is justified, then grep an anchor pattern and read each candidate to confirm the shape (a grep hit is not a finding).

Modelling finders (~7, one per representation smell) work smell-first too, but grounded in the code-style/* + data-types/* docs (option, either, data, branded-types, chunk, trait/equal, dual): they hunt the type of data and state — null over Option, sentinels over Either, flags over a tagged union, bare primitives over branded types, in-place mutation over immutable structures, hand equality over Equal, data-first helpers over data-last. Three of them deliberately border a structural or substitution smell (sentinel-or-throw vs throw-in-effect, in-place-mutation vs mutable-state, hand-equality/ nullable-return vs the Equal/Option domains); each finder states its boundary so the axes don't double-count.

Behaviour finders (~5, one per dynamic smell) work smell-first too, grounded in the concurrency/*, error-management/*, and schema/* docs (basic-concurrency, fibers, two-error-types, getting-started): they hunt how effects run (sequential-not-concurrent, unbounded-fanout), fail (untyped-error-channel), and what they trust (unvalidated-boundary, unsupervised-fork). Each anchors on a present construct (an Effect.all/fork, an as/JSON.parse, a typed E) and confirms a concrete misuse — for concurrency the data dependency between effects is the whole question. Three border an existing axis (unvalidated-boundary vs internal-bridge/bare-primitive, untyped-error-channel vs throw-in-effect, unsupervised-fork vs mutable-state); each states its boundary.

Findings then flow — per-finding, no barrier — into an adversarial verify pass: one refuter per finding. The axes split into two opposite default verdicts, because their failure modes are opposite:

• Substitution — the refuter tries to disprove the swap (false twin) and defaults to refuted when unsure. A plausible-but-wrong helper swap is the risk, so the bar is "positively confirm the swap preserves behaviour."
• Structural, modelling & behaviour — the refuter asks only is this a false positive — not actually a non-Effect-native shape, representation, or misuse? and defaults to surfaced when unsure. It refutes only a misread or a genuinely-justified choice; "is the rewrite worth the blast radius" is a gate concern, not a refutation ground (else it kills true smells like ZulipHttp, which it agrees are real, on "not clearly worth it"). A surfaced false positive is cheaply cut at the gate; a refuted true smell is invisible. Two refuters carry an extra guard against over-flagging: data-first-helper kills a data-last rewrite that would be gratuitous point-free (composability is the goal, not currying); and sequential-not-concurrent refutes when the effects are genuinely data-dependent and so must be sequential.

A synthesis agent writes the report (deduping cross-axis sightings as it reasons about the prose). The confirmed / low-confidence issue partition is NOT trusted to that agent — the workflow derives it deterministically from each survivor's own confidence (dedup by file:line, highest confidence wins, then split). An LLM asked to losslessly re-split survivors drops and misfiles them.

Running it

1. Get today's date (date +%F).

2. Launch the workflow, passing the date so the epic and report file are named:

   Workflow({
     scriptPath: '.claude/skills/effect-native-audit/effect-native-audit.workflow.js',
     args: { date: '<YYYY-MM-DD>' },
   })

   It runs in the background (~41 finders — 23 substitution + 6 structural + 7 modelling + 5 behaviour — ~10 concurrent, then verify + synth); you are notified on completion. Watch live with /workflows. To run a single axis (cheaper re-run after editing its prompts, or to resume just one), pass args: { date, axes: ['behaviour'] }.

3. The workflow writes the report to docs/effect-native-audit-<date>.md and returns { confirmed[], lowConfidence[], refutedCount, coverage }.

After it returns — gate, then file

The workflow returns findings and does not file them. A sweep can surface ~25 items, and filing them all unreviewed clogs the backlog.

The report is working scaffolding for the review, not a permanent record. File what is worth keeping, then delete docs/effect-native-audit-<date>.md.

1. Present the confirmed[] list to the maintainer — file:line, rolled → native, why. Also surface the lowConfidence[] items so any worth keeping can be promoted; un-promoted ones are dropped with the report.
2. Wait for go-ahead. The maintainer may cut or downgrade confirmed items, or promote low-confidence ones, first.
3. File each approved finding as its own issue, grouped under one tracking issue. Each description must be self-contained (file:line, the rewrite, the why, source/line, docsRef) because it has to stand on its own once the report is gone. Structural, modelling, and behaviour findings must carry their blastRadius (the call sites a rewrite ripples to — a representation change moves every producer and consumer of the value). Do not point at the report; it won't survive.

Each filed item is its own native swap; implement them separately with TDD, not as a batch.

Notes

• Source AND docs are both mandatory. For substitution, source gives the inventory (you can't grep ^export from a prose page) and docs give the judgment; for structural, modelling, and behaviour, the design docs ARE the ground (the smell is a shape, a representation, or a dynamic policy, not an export). A finder with only one over-suggests or mis-verifies. See domains.md.
• Two local clones. Effect source at ~/Development/references/effect; Effect docs at ~/Development/references/effect-website (Astro/Starlight — the URL …/docs/<slug>/ maps exactly to …/docs/docs/<slug>.mdx, and a multi-page section is a directory the finder reads in full). Both are workstation-local; a cloud/CI agent falls back to GitHub-raw source + WebFetch docs, just slower. The coverage section flags any fallback.
• Refresh on Effect bumps. Source paths and docs slugs drift with releases — domains.md carries the checklist. The authoritative sets are the DOMAINS, STRUCTURAL_SMELLS, MODELLING_SMELLS, and BEHAVIOUR_SMELLS arrays in the workflow script; domains.md mirrors them for humans.
• No auto-fix. Findings become tracked work, not an automated diff.