name	effect-style-error-modeling
description	Models success and failure explicitly in TypeScript using Result or Either-like flows instead of uncontrolled exceptions. Use when implementing predictable error propagation across async workflows.

Effect-Style Error Modeling

Rule Anchor

AGENTS.md > "No Fallback Policy" (Result type mandatory for failable public functions)
AGENTS.md > "Development Patterns"

The No-Fallback rule (owned by code-quality.md) is the constraint; this skill owns only the Result-vs-throw decision method. Model errors as data (type Result<T, E> = { ok: true; value: T } | { ok: false; error: E }), define domain-specific error unions, map external exceptions to typed variants once at the boundary adapter, and keep one canonical error path per use case. Never convert terminal failure into active processing without a separately gated, explicitly authorized policy path.

When to Use Result vs Throw

Scenario	Use	Rationale
Domain operation that can fail (validation, not found, conflict)	`Result<T, E>`	Caller must handle failure explicitly
Truly unexpected programmer error (assertion, invariant violation)	`throw`	Should crash, not be silently handled
External SDK/API call boundary	`Result<T, E>` via boundary adapter	Convert exception to typed error at boundary
Internal helper called only by Result-returning functions	Either	Match the caller's convention

Decision rule: if the caller should reasonably handle the failure, return Result. If the failure means a bug in the code, throw. Do not mix throw and Result randomly in one flow, and never catch-everything into a generic fallback success.

name	effect-style-error-modeling
description	Models success and failure explicitly in TypeScript using Result or Either-like flows instead of uncontrolled exceptions. Use when implementing predictable error propagation across async workflows.