effect-best-practices

name	effect-best-practices
version	0.1.0
description	Local Effect doctrine for the pi healthcare harness. Use when a task touches files importing effect and needs consistent rules for services, schemas, errors, layers, config, and structured effectful composition.
allowed-tools	["Read"]

effect-best-practices

Goal

Keep the harness on one Effect style so builder and reviewer do not improvise different patterns for contracts, runtime services, and failures.

Apply when

• The task edits files that import from effect.
• The task introduces or changes Schema boundary contracts.
• The task adds runtime services, typed errors, config loading, or logging.

Rules

• Use Schema for external contracts, agent handoffs, and runtime boundary data.
• Use branded identifiers when IDs cross meaningful service or contract boundaries.
• Use Schema.TaggedError for domain and transport errors that need stable structure.
• Prefer specific domain errors over generic HTTP or catch-all errors.
• Handle typed failures with catchTag or catchTags, not broad catchAll rewrites that erase intent.
• Use Effect.Service for business services and declare dependencies in the service definition.
• Compose runtime dependencies with layers at the app boundary, not with ad hoc provide chains at random call sites.
• Use Effect.fn for named effectful operations that deserve stable tracing and reviewable boundaries.
• Use Effect.log with structured fields instead of console.log.
• Use Config with validation instead of reading process.env directly in domain or service logic.
• Prefer explicit optional handling over nullable domain state when the contract needs to preserve meaning.
• Do not call runSync or runPromise inside domain services.

Review categories

• contracts and schemas
• errors
• service and layer boundaries
• effectful composition
• config and logging
• optional and nullable data
• dependency admission drift

Out of scope

• React atom patterns
• UI state conventions
• non-Effect framework doctrine outside this harness