# Resilience

> Adds retry, timeout, circuit breaker, and backoff strategies around fallible operations returning Results. Use this skill when hardening workflows against transient failures or composing resilient sagas. Do not use when/for defining Result types themselves (use result-types) or HTTP rate-limit headers alone (use api-design).

- Skill: `jagreehal/resilience` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add jagreehal/resilience`
- Raw SKILL.md: https://api.skillmd.com/api/skills/jagreehal/resilience/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: jagreehal (https://skillmd.com/u/jagreehal)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/jagreehal/resilience

---


# Resilience Patterns

## Critical rules

- Resilience is composition: `step.retry` / `step.withTimeout` at the workflow — never inside business functions.
- Retry at exactly one layer. Never double-retry (3×3×3 storms).
- Retry only transient errors. Never retry non-idempotent writes without an idempotency key.
- Always set per-attempt timeouts and enable jitter in production.
- Multi-step retries require every step to be idempotent. Use circuit breakers for sticky-down externals.
- Before configuring policies, read [references/patterns.md](references/patterns.md) and [references/defaults.md](references/defaults.md).

## Workflow

1. Keep `fn(args, deps)` returning Results with no retry loops.
2. Choose defaults from [references/defaults.md](references/defaults.md) for the operation type.
3. Wrap with `step.retry` + per-attempt `timeout` + `jitter` + `retryOn` for transient codes only.
4. For writes, require an idempotency key or do not retry.
5. Detect timeouts with `isStepTimeoutError` / `getStepTimeoutMeta` and log.
6. Add circuit breakers (opossum/cockatiel) for externals that stay down.

## Resources

- [references/patterns.md](references/patterns.md) — retry/timeout/jitter examples, circuit breakers, rationalizations. Read when implementing.
- [references/defaults.md](references/defaults.md) — recommended attempts/backoff/timeouts. Read when choosing policy.

## Validation

- [ ] Retry only at workflow level; single layer
- [ ] `retryOn` matches only transient errors
- [ ] Non-idempotent writes gated by idempotency key or not retried
- [ ] Per-attempt timeout; jitter + backoff in production
- [ ] Timeout errors detected and logged
- [ ] Underlying function tests unchanged

## Constraints

- Do not put retry inside business functions or stack retries across API/service/client for the same call.
- Related: `result-types`, `fn-args-deps`, `api-design`, `observability`.