Effect Solutions Compliance Audit

Scan repository against Effect TypeScript best practices from effect.solutions. Use this skill to perform systematic audits of Effect code compliance.

Prerequisites

Before scanning, load current recommendations:

effect-solutions list

Read targeted references:

references/error-handling.md

references/testing-layers.md

Load the effect-ts skill for best practices context:

skill({ name: "effect-ts" })

Audit Checklist

1. TypeScript Configuration

Check

tsconfig.base.json

(or

tsconfig.json

) for:

exactOptionalPropertyTypes: true

strict: true

noUnusedLocals: true

declarationMap: true

sourceMap: true

Effect Language Service plugin configured

Correct

module

setting for project type (preserve/bundler for apps, NodeNext for libraries)

Run:

effect-solutions show tsconfig

2. Services & Layers Pattern

Search for Effect services and check:

Are services defined with

Context.Tag

?

Do tag identifiers use

@path/ServiceName

pattern?

Are layers defined with

Layer.effect

or

Layer.sync

?

Is there a single

Effect.provide

at entry point?

Run:

effect-solutions show services-and-layers

3. Data Modeling

Check for:

Use of

Schema.Class

for records

Use of

Schema.TaggedClass

for variants

Branded types for primitives (IDs, emails, etc.)

Pattern matching with

Match.valueTags

Run:

effect-solutions show data-modeling

4. Error Handling

Check for:

Use of

Schema.TaggedError

for domain errors

Proper error recovery with

catchTag

/

catchTags

Appropriate use of defects vs typed errors

Run:

effect-solutions show error-handling

5. Configuration

Check for:

Use of

Schema.Config

for validation

Config service layer pattern

Config.redacted

for secrets

Run:

effect-solutions show config

6. Testing

Check for:

Use of

@effect/vitest

it.effect()

for Effect tests

Test layer composition patterns

Run:

effect-solutions show testing

7. Runtime Usage Anti-Pattern (

Effect.runPromise

in Production)

Search for

Effect.runPromise

in production code (exclude

tests/

,

*.test.ts

,

agent-tools/

).

Effect.runPromise

uses the default runtime with NO layers

— no tracer, no config, no observability. Effect spans (

Effect.fn

,

Effect.withSpan

) will be invisible to Sentry/OpenTelemetry.

Production code MUST use

runtime.runPromise

(from

ManagedRuntime

in

effect-runtime.ts

) which includes

AppLayer

with

SentryTracingLive

If

runtime.runPromise

is not possible (circular deps), the code MUST add

Effect.provide(SentryTracingLive)

to the pipe chain

Test files are exempt (they provide their own layers)

Search patterns:

Effect.runPromise(

in

apps/web-app/src/

(excluding

tests/

)

Effect.runSync(

in

apps/web-app/src/

(excluding

tests/

)

Report each occurrence with:

File path and line

Whether it's using

runtime.runPromise

(✅) or bare

Effect.runPromise

(❌)

Whether

SentryTracingLive

is provided in the pipe chain (fallback ✅)

Run:

effect-solutions show services-and-layers

8. Option/Either Internal Tag Anti-Patterns

Check for direct

_tag

branching on

Option

/

Either

in production code and tests.

Production code: report all direct

_tag

usage as findings with replacement recommendation

Tests: allow

_tag

assertions for domain error identity, but flag control-flow branching patterns that should use helpers

Prefer:

Either.match

,

Either.isLeft

,

Either.isRight

Option.match

,

Option.isSome

,

Option.isNone

,

Option.getOrElse

Search patterns to include:

if (.*._tag === "Left")

if (.*._tag === "Right")

if (.*._tag === "Some")

if (.*._tag === "None")

expect(.*._tag)

Run:

effect-solutions show error-handling

Output Format

Provide a structured report with:

Summary

Overall compliance score (e.g., 7/10)

What's Working Well

List patterns that follow best practices

Improvements Needed

List specific issues with:

File location

Current pattern

Recommended pattern

Priority (high/medium/low)

Scope label:

production

or

test

Quick Wins

Easy fixes that can be done immediately

Next Steps

Recommended order of improvements