error-handling

Goal: failures that are visible, contextual, and handled deliberately. Use for: - deciding how functions signal and propagate failure - reviewing try/catch, error types, and recovery - fixing swallowed errors and vague messages Workflow: 1. Distinguish expected failures from programmer bugs. 2. Model expected errors explicitly (results or typed exceptions). 3. Handle errors where you can act; otherwise propagate with context. 4. Add context as errors cross boundaries, without losing the cause. 5. Fail fast on invariant violations; do not limp on. 6. Surface actionable messages; log details once, near the source. Patterns: - typed errors or result types over generic throws - wrap-and-rethrow to add context, preserving the cause - retry with backoff for transient failures only - a single place that maps errors to user-facing responses Rules: - never swallow an error silently - do not catch broadly just to continue; handle or rethrow - include context, never the bare message - distinguish retryable failures from permanent ones