error-handling-and-resilience

Error Handling and Resilience

Overview

Define the project's failure philosophy before failures happen. Output is .forge/error-handling.md — an error-class taxonomy, retry and timeout discipline, circuit breaker policy, graceful degradation paths, user-facing error message rules, and rollback/compensation patterns for irreversible flows. Downstream skills (observability, incident-response-and-postmortems) consume this file.

When to Use

• A new service is being designed and needs an error model before code lands
• An incident revealed a silently-swallowed failure
• External calls (DB, API, queue, LLM) are being added to a hot path
• Code review is flagging inconsistent error handling across modules
• Production logs are full of unclassified errors with no caller action

When NOT to Use

• The codebase already has a documented error taxonomy and the change is local to one module
• One-off scripts or throwaway prototypes
• The work is a config tweak with no failure surface

Common Rationalizations

Thought	Reality
"try-catch is enough"	Bare catch swallows context. Without classification, the same handler runs for transient DB blips and bad user input.
"We'll add retries later"	Retries are architectural — adding them after the fact requires every caller to change.
"Errors are rare"	Rare errors in production are the ones that page you at 3am. They're rare because they require specific conditions, not because they don't matter.
"Just log and continue"	Silent failures compound. Downstream code now sees inconsistent state and no signal that something went wrong.
"External call without timeout is fine, the library has defaults"	Library defaults are usually 30s-infinity. Your user is gone in 8 seconds.
"Retry forever, eventually it'll work"	Retry storms amplify outages. Without a cap, you DDoS yourself.

Red Flags

• try { ... } catch (e) {} — empty catch
• console.log(err); return — log and continue without classification
• while (true) { try { ... } catch { } } — unbounded retry
• if (err.message.includes("not found")) — string-matching errors
• Promise without .catch or async function without try
• fetch(url) with no timeout, no AbortController, no deadline
• No distinction between transient (retry) and permanent (escalate) failures
• "Error handling: TBD" anywhere in a contract