vanara 0.1.0 → 0.2.0

package/catalog/skills/error-handling-patterns/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: error-handling-patterns
+description: How to handle errors explicitly and consistently across an app — validate at boundaries, classify operational vs programmer errors, add context while propagating, retry transient failures with backoff, and never swallow. Covers JS/Python/Go/Rust patterns with runnable checks.
+type: skill
+version: 2.0.0
+updated: 2026-06-29
+---
+# Error Handling Patterns
+
+Errors are part of the contract, not an afterthought. A robust system **handles errors where it can act,
+propagates them where it can't, and never lets a failure vanish silently**. This skill is the deep
+reference: the decisions, the trade-offs, and the anti-patterns. Heavy detail lives in `references/`,
+copy-paste material in `examples/`, and a runnable linter for swallowed errors in `scripts/`.
+
+## Mental model
+
+Every error sits on two axes that decide what you do with it:
+
+| Axis | Question | Consequence |
+|---|---|---|
+| **Operational vs programmer** | Is this an expected runtime condition (network down, bad input) or a bug (null deref, broken invariant)? | Operational → recover/retry/surface. Programmer → fail fast, let it crash, fix the code. |
+| **Recoverable vs fatal** | Can the caller do something useful about it here? | Yes → handle locally. No → add context and propagate. |
+
+Classifying wrong is the root cause of most bad error handling: retrying a programmer bug forever, or
+crashing the process over a single bad HTTP request. The full taxonomy is in
+[`references/error-taxonomy.md`](references/error-taxonomy.md).
+
+## The five rules
+
+1. **Validate at the boundary.** Reject bad input early with a clear, specific message (fail fast). Never
+   trust data crossing a trust boundary — HTTP bodies, env vars, file contents, API responses.
+2. **Classify the error.** Operational errors are values you handle; programmer errors are bugs you
+   surface loudly. Don't `catch` a `TypeError` to "be safe".
+3. **Add context as you propagate.** Wrap with *what you were doing* and preserve the original cause and
+   stack (`new Error(msg, { cause })` in JS, `fmt.Errorf("...: %w", err)` in Go).
+4. **One owner for user-facing messaging.** Translate to a friendly message at the edge (the HTTP layer,
+   the UI). Keep full detail in server-side logs only — never leak stack traces to users.
+5. **Never swallow.** An empty `catch {}`, a bare `except: pass`, or a `.catch(() => {})` is a defect.
+   Run `scripts/lint-empty-catch.mjs` in CI to catch these automatically.
+
+## Adding context without losing the cause
+
+The single most valuable habit: wrap errors with context while chaining the original, so the final log
+shows the full causal trail from the low-level failure up to the request that triggered it.
+
+```js
+// Node 16.9+ supports the standard `cause` option on Error.
+async function placeOrder(userId, cart) {
+  try {
+    const order = await db.orders.insert({ userId, items: cart.items });
+    return order;
+  } catch (err) {
+    // Wrap: keep the DB error as `cause`, add the business context.
+    throw new Error(`failed to place order for user ${userId}`, { cause: err });
+  }
+}
+```
+
+```python
+# Python's `raise ... from` preserves the chain (shown as "The above exception
+# was the direct cause of the following exception" in the traceback).
+def place_order(user_id, cart):
+    try:
+        return db.orders.insert(user_id=user_id, items=cart.items)
+    except DBError as err:
+        raise OrderError(f"failed to place order for user {user_id}") from err
+```
+
+Language-by-language patterns (try/catch vs `Result`/`Either` vs panics) are in
+[`references/language-patterns.md`](references/language-patterns.md).
+
+## Retrying transient failures
+
+Only **operational, transient, idempotent** failures are safe to retry — a 503 or a connection reset,
+not a 400 or a `NullPointerException`. Retry with **exponential backoff plus full jitter** to avoid
+synchronized retry storms (the "thundering herd"), and always cap attempts and total time.
+
+```js
+async function withRetry(fn, { retries = 4, baseMs = 100, isRetryable } = {}) {
+  let attempt = 0;
+  for (;;) {
+    try {
+      return await fn();
+    } catch (err) {
+      attempt++;
+      if (attempt > retries || (isRetryable && !isRetryable(err))) throw err;
+      const backoff = baseMs * 2 ** (attempt - 1);
+      const jittered = Math.random() * backoff; // full jitter
+      await new Promise((r) => setTimeout(r, jittered));
+    }
+  }
+}
+```
+
+When NOT to retry, circuit breakers, and budgets are covered in
+[`references/retry-and-backoff.md`](references/retry-and-backoff.md).
+
+## Common pitfalls (anti-patterns)
+
+- **Swallowing errors** — empty `catch {}`, `except: pass`, `.catch(() => {})`, or `if err != nil {}` in
+  Go. The failure disappears and you debug blind. This is the #1 defect; lint for it.
+- **Catch-log-rethrow-wrapped duplication** — logging *and* rethrowing at every layer produces the same
+  error logged ten times. Log once, at the boundary that owns the response.
+- **Catching too broadly** — `except Exception` or `catch (e)` that also eats `KeyboardInterrupt`,
+  programmer bugs, or `OutOfMemory`. Catch the narrowest type you can actually handle.
+- **Returning a sentinel instead of erroring** — returning `null`/`-1`/`{}` on failure forces every
+  caller to remember the magic check; most won't. Prefer throwing or a `Result` type.
+- **Leaking internals to users** — returning raw stack traces or SQL errors is both bad UX and a security
+  leak (reveals schema, file paths, library versions).
+- **Retrying non-idempotent or non-transient operations** — retrying a `POST /charge` on timeout can
+  double-charge; retrying a `400` just wastes time. See the retry reference.
+- **Losing the original cause** — `throw new Error("save failed")` without `{ cause }` discards the stack
+  that tells you *why*.
+
+## When NOT to use / trade-offs
+
+- **Don't catch programmer errors to keep running.** A bug that corrupted state should crash the process
+  (let a supervisor like systemd/k8s/PM2 restart it clean) rather than limp along with bad data.
+- **Don't add a `Result`/`Either` type to a small script** — the ceremony outweighs the benefit. Plain
+  exceptions are fine when there's one boundary and one owner.
+- **Don't retry by default.** Retries amplify load during incidents and can mask a real outage; only
+  retry classified-transient, idempotent calls, and always with a budget.
+- **Defensive `try/catch` everywhere is a smell**, not safety. It scatters handling, hides bugs, and
+  makes control flow unreadable. Handle at meaningful boundaries.
+
+## Files in this package
+
+- [`references/error-taxonomy.md`](references/error-taxonomy.md) — operational vs programmer errors, and how the distinction drives recovery
+- [`references/retry-and-backoff.md`](references/retry-and-backoff.md) — when to retry, exponential backoff, jitter, circuit breakers, budgets
+- [`references/language-patterns.md`](references/language-patterns.md) — try/catch vs `Result`/`Either` vs panics across JS, Python, Go, Rust
+- [`examples/express-error-middleware.js`](examples/express-error-middleware.js) — a complete centralized error handler with an `AppError` class
+- [`examples/result-pattern.ts`](examples/result-pattern.ts) — a typed `Result<T, E>` with helpers, no exceptions for expected failures
+- [`scripts/lint-empty-catch.mjs`](scripts/lint-empty-catch.mjs) — runnable Node linter that flags swallowed errors; supports `--selftest`
+
+Pairs with the `code-reviewer` agent, the `silent-failure-hunter` agent, the `rest-api-design` skill
+(for the HTTP error envelope), and the `owasp-top10` skill (for not leaking sensitive data in errors).

package/catalog/skills/error-handling-patterns/examples/express-error-middleware.js

@@ -0,0 +1,93 @@
+// Centralized error handling for an Express app.
+//
+// Pattern: routes never format error responses themselves. They throw (or pass
+// to next()) typed AppErrors, and ONE error-handling middleware translates them
+// to a consistent HTTP envelope, logs full detail server-side, and hides
+// internals from the client.
+//
+// Run a quick demo:  node express-error-middleware.js   (no deps; uses a fake req/res)
+
+// --- 1. A typed, operational error -----------------------------------------
+
+class AppError extends Error {
+  constructor(message, { code, status = 500, retryable = false, cause } = {}) {
+    super(message, { cause });
+    this.name = 'AppError';
+    this.code = code; // stable, machine-readable: 'order_not_found'
+    this.status = status; // maps to HTTP status
+    this.retryable = retryable;
+    this.isOperational = true; // distinguishes from programmer bugs
+  }
+}
+
+// Convenience constructors for common cases.
+const NotFound = (msg, code = 'not_found') => new AppError(msg, { code, status: 404 });
+const BadRequest = (msg, code = 'bad_request') => new AppError(msg, { code, status: 400 });
+const Conflict = (msg, code = 'conflict') => new AppError(msg, { code, status: 409 });
+
+// --- 2. Wrap async route handlers so rejections reach the error middleware --
+// Without this, a thrown error in an async handler becomes an unhandledRejection
+// instead of hitting Express's error pipeline.
+const asyncHandler = (fn) => (req, res, next) =>
+  Promise.resolve(fn(req, res, next)).catch(next);
+
+// --- 3. The ONE error-handling middleware (must have 4 args) ----------------
+
+function errorMiddleware(logger) {
+  return (err, req, res, _next) => {
+    const operational = err instanceof AppError && err.isOperational;
+    const status = operational ? err.status : 500;
+
+    // Log full detail server-side ALWAYS — including the cause chain.
+    logger.error('request failed', {
+      method: req.method,
+      path: req.path,
+      status,
+      code: err.code,
+      message: err.message,
+      cause: err.cause && String(err.cause),
+      stack: err.stack,
+    });
+
+    // Never leak internals to the client on a non-operational (bug) error.
+    const body = operational
+      ? { data: null, error: { code: err.code, message: err.message } }
+      : { data: null, error: { code: 'internal_error', message: 'Something went wrong.' } };
+
+    res.status(status).json(body);
+  };
+}
+
+// --- 4. Example routes ------------------------------------------------------
+// app.get('/orders/:id', asyncHandler(async (req, res) => {
+//   const order = await db.orders.find(req.params.id);
+//   if (!order) throw NotFound(`order ${req.params.id} not found`, 'order_not_found');
+//   res.json({ data: order, error: null });
+// }));
+// app.use(errorMiddleware(logger)); // registered LAST, after all routes.
+
+// --- Tiny self-contained demo (no Express needed) --------------------------
+
+function demo() {
+  const logger = { error: (m, ctx) => console.log(`[log] ${m}`, ctx.code, '|', ctx.message) };
+  const handle = errorMiddleware(logger);
+  const fakeReq = { method: 'GET', path: '/orders/42' };
+  const fakeRes = {
+    status(s) { this._s = s; return this; },
+    json(b) { console.log(`-> HTTP ${this._s}`, JSON.stringify(b)); },
+  };
+
+  console.log('Operational error (safe to show user):');
+  handle(NotFound('order 42 not found', 'order_not_found'), fakeReq, fakeRes);
+
+  console.log('\nProgrammer bug (internals hidden from user):');
+  handle(new TypeError("Cannot read properties of undefined (reading 'id')"), fakeReq, fakeRes);
+}
+
+export { AppError, NotFound, BadRequest, Conflict, asyncHandler, errorMiddleware };
+
+// Run the demo when executed directly (robust on Windows paths with spaces).
+import { fileURLToPath } from 'node:url';
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  demo();
+}

package/catalog/skills/error-handling-patterns/examples/result-pattern.ts

@@ -0,0 +1,81 @@
+// A typed Result<T, E> for TypeScript: model *expected* failures as values so the
+// compiler forces callers to handle them, instead of throwing for control flow.
+//
+// Reserve `throw` for programmer errors / truly exceptional paths. Use Result for
+// validation, "not found", parse failures, and other ordinary outcomes.
+
+// --- The type --------------------------------------------------------------
+
+export type Ok<T> = { readonly ok: true; readonly value: T };
+export type Err<E> = { readonly ok: false; readonly error: E };
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export const ok = <T>(value: T): Ok<T> => ({ ok: true, value });
+export const err = <E>(error: E): Err<E> => ({ ok: false, error });
+
+// --- Helpers ---------------------------------------------------------------
+
+/** Transform the success value, leaving errors untouched. */
+export function map<T, U, E>(r: Result<T, E>, fn: (t: T) => U): Result<U, E> {
+  return r.ok ? ok(fn(r.value)) : r;
+}
+
+/** Chain operations that can themselves fail (railway-oriented). */
+export function flatMap<T, U, E>(
+  r: Result<T, E>,
+  fn: (t: T) => Result<U, E>,
+): Result<U, E> {
+  return r.ok ? fn(r.value) : r;
+}
+
+/** Provide a fallback for the error case. */
+export function unwrapOr<T, E>(r: Result<T, E>, fallback: T): T {
+  return r.ok ? r.value : fallback;
+}
+
+/** Wrap a throwing function so its exception becomes an Err value. */
+export function tryCatch<T>(fn: () => T): Result<T, Error> {
+  try {
+    return ok(fn());
+  } catch (e) {
+    return err(e instanceof Error ? e : new Error(String(e)));
+  }
+}
+
+// --- Domain error type -----------------------------------------------------
+
+export type ValidationError = { code: 'validation'; field: string; message: string };
+
+// --- Example: validation that returns Result instead of throwing -----------
+
+interface SignupInput {
+  email: string;
+  age: number;
+}
+
+export function validateSignup(input: SignupInput): Result<SignupInput, ValidationError> {
+  if (!input.email.includes('@')) {
+    return err({ code: 'validation', field: 'email', message: 'must be a valid email' });
+  }
+  if (input.age < 18) {
+    return err({ code: 'validation', field: 'age', message: 'must be 18 or older' });
+  }
+  return ok(input);
+}
+
+// --- Usage: the caller CANNOT forget the error case (compiler enforces it) --
+
+export function handleSignup(input: SignupInput): string {
+  const result = validateSignup(input);
+  if (!result.ok) {
+    // result is narrowed to Err<ValidationError> here.
+    return `rejected: ${result.error.field} ${result.error.message}`;
+  }
+  // result is narrowed to Ok<SignupInput> here.
+  return `accepted: ${result.value.email}`;
+}
+
+// Example with chaining:
+//   const parsed = tryCatch(() => JSON.parse(raw));
+//   const validated = flatMap(parsed, (obj) => validateSignup(obj as SignupInput));
+//   const msg = validated.ok ? 'ok' : `bad: ${validated.error.message}`;

package/catalog/skills/error-handling-patterns/references/error-taxonomy.md

@@ -0,0 +1,91 @@
+# Error Taxonomy — Operational vs Programmer Errors
+
+The most important classification in error handling. Get it wrong and you either crash on recoverable
+conditions or limp along with corrupted state.
+
+## The two categories
+
+### Operational errors
+Expected runtime conditions a correct program will still encounter. They are **values to be handled**,
+not bugs.
+
+- Failed to connect to a server / connection reset
+- Request timed out
+- Server returned `503` / `429`
+- Invalid user input (failed validation)
+- File not found, disk full, permission denied
+- Out-of-money / out-of-stock business conditions
+
+**Response:** recover, retry (if transient + idempotent), or surface a clear message to the caller/user.
+These should *never* crash the process.
+
+### Programmer errors
+Bugs. The code is wrong. The program is now in a state its author did not anticipate.
+
+- `undefined is not a function` / `TypeError` / `AttributeError`
+- Reading a property of `null`
+- Passing the wrong type to a function
+- Forgetting to `await` a promise
+- A violated invariant / failed assertion
+
+**Response:** **fail fast and loud.** Do not `catch` them to "be safe". Let the process crash and let a
+supervisor (systemd, Kubernetes, PM2, a worker pool) restart it in a known-good state. Catching a bug to
+continue running risks acting on corrupted data.
+
+## Why the distinction drives everything
+
+| Decision | Operational | Programmer |
+|---|---|---|
+| Catch it? | Yes, where you can act | No — let it propagate to a top-level crash |
+| Retry it? | If transient + idempotent | Never (the bug is deterministic) |
+| Show the user? | A friendly, specific message | A generic "something went wrong" + 500, log internally |
+| Alert on it? | Rate/aggregate (it's expected sometimes) | Page someone — it's a bug |
+
+## Modeling operational errors as types
+
+Give operational errors a stable, machine-readable identity so callers and the HTTP layer can branch on
+them without string-matching messages.
+
+```js
+class AppError extends Error {
+  constructor(message, { code, status = 500, retryable = false, cause } = {}) {
+    super(message, { cause });
+    this.name = 'AppError';
+    this.code = code;          // e.g. 'order_not_found' — stable, machine-readable
+    this.status = status;      // maps to an HTTP status at the boundary
+    this.retryable = retryable;
+    this.isOperational = true; // distinguishes from programmer bugs
+  }
+}
+
+// At the top-level handler:
+function isOperational(err) {
+  return err instanceof AppError && err.isOperational === true;
+}
+```
+
+At your crash handler, **only** swallow-and-respond for `isOperational` errors; rethrow everything else
+so the process restarts.
+
+## The uncaught handler
+
+```js
+process.on('uncaughtException', (err) => {
+  logger.fatal('uncaught exception — crashing', { err });
+  // Do NOT resume. Flush logs, then exit; let the supervisor restart.
+  process.exit(1);
+});
+process.on('unhandledRejection', (reason) => {
+  // Promote to an exception so the above handler runs.
+  throw reason;
+});
+```
+
+## Pitfalls
+- **Treating all errors the same.** A blanket `try/catch` around `main()` that logs and continues turns
+  bugs into silent data corruption.
+- **Retrying programmer errors.** They're deterministic — the retry fails identically while burning time
+  and load.
+- **A "500 for everything" API.** Validation failures are operational and should be `400/422`, not `500`.
+- **Catching to add a log then re-throwing at every layer** — you get the same bug logged N times with no
+  added signal. Decide one owner.

package/catalog/skills/error-handling-patterns/references/language-patterns.md

@@ -0,0 +1,102 @@
+# Language Patterns — Exceptions vs Result vs Panics
+
+Different languages encode failure differently. Using the idiom the language was designed for keeps code
+readable and tooling effective.
+
+## JavaScript / TypeScript — exceptions + `cause`
+
+Throw/`try`/`catch` is idiomatic. Since Node 16.9 / ES2022, always chain the cause:
+
+```js
+try {
+  await writeFile(path, data);
+} catch (err) {
+  throw new Error(`failed to persist ${path}`, { cause: err });
+}
+```
+
+For *expected* failures (validation, "not found") in TypeScript, a `Result` type makes the failure path
+explicit in the signature and forces the caller to handle it — see [`result-pattern.ts`](../examples/result-pattern.ts).
+Reserve `throw` for exceptional/programmer paths.
+
+Async caveat: a rejected promise that isn't `await`ed or `.catch`ed becomes an `unhandledRejection`.
+Never write `.catch(() => {})` to silence it — that's swallowing.
+
+## Python — exceptions + `raise from`
+
+Exceptions are the idiom. Preserve the chain and catch narrowly:
+
+```python
+try:
+    config = json.loads(raw)
+except json.JSONDecodeError as err:
+    raise ConfigError("config file is not valid JSON") from err
+```
+
+- Catch the **narrowest** exception (`except KeyError`, not bare `except:`).
+- A bare `except:` even catches `KeyboardInterrupt`/`SystemExit` — almost always a bug.
+- Use `else` for the success path and `finally` for cleanup; or a context manager (`with`) for
+  acquire/release so cleanup can't be forgotten.
+
+```python
+# Anti-pattern this skill's linter flags:
+try:
+    do_thing()
+except Exception:
+    pass   # swallowed — the failure is now invisible
+```
+
+## Go — errors as values
+
+Go has no exceptions for ordinary failures; errors are returned values you must check. Wrap with `%w` to
+preserve the chain, then unwrap with `errors.Is`/`errors.As`.
+
+```go
+func loadUser(id string) (*User, error) {
+    u, err := db.Get(id)
+    if err != nil {
+        return nil, fmt.Errorf("loadUser %s: %w", id, err)
+    }
+    return u, nil
+}
+
+// caller:
+if err != nil {
+    if errors.Is(err, sql.ErrNoRows) { /* operational: 404 */ }
+    return err // propagate with context already attached
+}
+```
+
+- `panic` is for **programmer errors / unrecoverable** states only — not control flow.
+- `if err != nil {}` with an empty body is the Go form of swallowing.
+- `recover()` belongs at goroutine/server boundaries to stop one bad request from crashing the process,
+  not as a general try/catch.
+
+## Rust — `Result<T, E>` and `?`
+
+Failure is in the type system. `Result<T, E>` must be handled (the compiler warns on an unused one), and
+`?` propagates concisely while converting error types via `From`.
+
+```rust
+fn read_config(path: &str) -> Result<Config, ConfigError> {
+    let raw = std::fs::read_to_string(path)?;      // io::Error -> ConfigError via From
+    let cfg: Config = toml::from_str(&raw)?;       // toml error -> ConfigError via From
+    Ok(cfg)
+}
+```
+
+- `Option<T>` models absence; `Result<T, E>` models failure with a reason.
+- `panic!`, `.unwrap()`, `.expect()` are for unrecoverable/programmer errors — avoid in library code.
+- Crates like `thiserror` (typed library errors) and `anyhow` (application-level context) are the
+  ecosystem standard.
+
+## Cross-cutting principles
+
+| Principle | JS/TS | Python | Go | Rust |
+|---|---|---|---|---|
+| Preserve cause | `{ cause }` | `raise ... from` | `%w` + `errors.Is/As` | `source()` / `?` + `From` |
+| Expected-failure idiom | `Result` type | exceptions | error return | `Result<T,E>` |
+| Programmer-error idiom | `throw` (crash) | exception (crash) | `panic` | `panic!`/`unwrap` |
+| Swallow anti-pattern | `.catch(()=>{})` | `except: pass` | `if err != nil {}` | `let _ = ...;` ignoring `Result` |
+
+The throughline: **make failure explicit, preserve the cause, handle at a boundary, and never silence.**

package/catalog/skills/error-handling-patterns/references/retry-and-backoff.md

@@ -0,0 +1,76 @@
+# Retry & Backoff
+
+Retries turn transient failures into success — or turn a small blip into a self-inflicted outage. The
+difference is discipline: retry only the right errors, back off exponentially, add jitter, and cap the
+budget.
+
+## What is safe to retry
+
+A call is retry-safe only if **all three** hold:
+
+1. **Operational + transient** — `503`, `429`, connection reset, timeout. Not `400`, `401`, `404`, `422`,
+   and never a programmer bug.
+2. **Idempotent** — the same call twice has the same effect. `GET`, `PUT`, `DELETE` usually qualify.
+   `POST` does *not* unless protected by an idempotency key.
+3. **Within budget** — you have attempts and time left.
+
+Retrying a non-idempotent `POST /charge` after a timeout can double-charge the customer (the first
+request may have succeeded; only the *response* was lost). Use an `Idempotency-Key` so the server
+deduplicates — see the `rest-api-design` skill.
+
+## Exponential backoff with jitter
+
+Fixed-interval retries from many clients synchronize into waves that hammer a recovering service (the
+**thundering herd**). Exponential backoff spreads attempts out; **jitter** desynchronizes clients.
+
+```js
+// Full jitter (AWS-recommended): sleep = random(0, base * 2**attempt), capped.
+function backoffDelay(attempt, { baseMs = 100, capMs = 10_000 } = {}) {
+  const exp = Math.min(capMs, baseMs * 2 ** attempt);
+  return Math.random() * exp;
+}
+```
+
+| Strategy | Behavior | Verdict |
+|---|---|---|
+| Fixed delay | every client retries at the same cadence | thundering herd |
+| Exponential, no jitter | spreads over time but clients still align | better, still synchronized |
+| Exponential + **full jitter** | random spread over the window | **recommended default** |
+
+## Caps and budgets
+
+- **Max attempts:** typically 3–5. Beyond that you're usually masking a real outage.
+- **Total deadline:** cap wall-clock time (e.g. 30s) so a request doesn't hang the caller.
+- **Respect `Retry-After`:** if the server sends it (on `429`/`503`), honor it over your own backoff.
+- **Retry budget:** limit retries to a small fraction (e.g. 10%) of total requests so retries can't more
+  than ~double load during an incident.
+
+## Circuit breakers
+
+When a dependency is clearly down, stop sending it traffic — retries just pile on. A circuit breaker
+tracks the recent failure rate and **opens** (fails fast) past a threshold, periodically letting a
+**half-open** trial request through to test recovery.
+
+```
+CLOSED  --(failures > threshold)-->  OPEN  --(cooldown elapsed)-->  HALF-OPEN
+   ^                                                                    |
+   +--------------------(trial request succeeds)------------------------+
+                         (trial fails -> back to OPEN)
+```
+
+This protects the failing service (lets it recover) and the caller (fails fast instead of waiting on
+timeouts).
+
+## Timeouts come first
+
+Retries are pointless without timeouts — a hung connection with no timeout never fails, so it never
+retries. Always set a per-attempt timeout *and* an overall deadline. `AbortController` (JS),
+`context.WithTimeout` (Go), and `asyncio.wait_for` (Python) are the standard tools.
+
+## Pitfalls
+- **Retrying everything** — retrying `400`/`401`/`422` is pure waste; they'll fail identically.
+- **No jitter** — synchronized retries DDoS your own recovering service.
+- **Unbounded retries** — a stuck dependency turns into an infinite loop and resource exhaustion.
+- **Retrying non-idempotent writes** without an idempotency key — duplicate charges, duplicate orders.
+- **Nested retries** — retry at the HTTP client *and* the service *and* the caller multiplies attempts
+  exponentially (3×3×3 = 27). Retry at exactly one layer.