1
---
2
name: retry-backoff-policy-calculator
3
description: Checks retry, backoff and timeout settings across a call chain to prevent retry storms. Computes exponential delay schedules with full, equal or decorrelated jitter, worst-case latency per layer, expected tries and request amplification. Flags inner timeouts that outlive the caller, retries of non-idempotent calls, retries on 4xx, ignored Retry-After and missing caps or deadlines. Includes a stdlib Python calculator with --self-test.
4
---
5
6
# Retry and Backoff Policy Calculator
7
8
You help engineers set retry, backoff and timeout policies that make services more reliable instead of turning a small outage into a big one. You collect the settings of every hop in a call chain (browser, gateway, services, databases, third-party APIs), compute what they really do under failure, and propose a safer policy with numbers.
9
10
## Files in this skill
11
12
- `scripts/retry_policy.py` - reads a call-chain JSON and prints delay schedules, worst-case latency, expected tries, amplification and flags (Python 3 standard library only)
13
- `references/backoff-math.md` - formulas for backoff, jitter, worst-case time, expected tries, amplification and timeout nesting
14
- `references/retry-safety-guide.md` - what is safe to retry, idempotency keys, circuit breakers, retry budgets, common library settings
15
- `templates/retry-policy-review.md` - review report with current chain, findings and proposed policy
16
- `examples/checkout-chain.json` - a three-layer checkout chain with typical mistakes
17
18
## Workflow
19
20
### 1. Map the chain
21
Ask for each hop, outermost first: attempts (total tries), base delay, multiplier, max delay, jitter type, per-try timeout, overall deadline, what it retries on (status codes, "timeout", "network"), whether the call is idempotent, whether an idempotency key is sent, and whether Retry-After is honored. Read them from code or config (SDK clients, HTTP client retry adapters, Envoy/Istio routes, gRPC service config, job queues). Unknown values: use the library default and mark them as assumed.
22
23
### 2. Run the calculator
24
```
25
python3 scripts/retry_policy.py examples/checkout-chain.json
26
python3 scripts/retry_policy.py chain.json --failure-rate 0.5 --max-amplification 8
27
python3 scripts/retry_policy.py chain.json --json > retry-report.json
28
python3 scripts/retry_policy.py --self-test
29
```
30
Exit code 1 means high-severity findings, 2 means bad input.
31
32
### 3. Explain the findings
33
Order: RETRY_UNSAFE and AMPLIFICATION first (they cause duplicate side effects and outages), then INNER_OUTLIVES_CALLER, HOT_LOOP, NO_PER_TRY_TIMEOUT, then medium and low. Explain each with the numbers from the report, for example "one checkout can become 36 calls to the payments provider".
34
35
### 4. Propose a fixed policy
36
Use `references/backoff-math.md` and `references/retry-safety-guide.md`: retry at one layer, full jitter with a cap, inner worst case below the caller's per-try timeout, deadlines passed down, idempotency keys for writes, no retries on 4xx except 408/429, Retry-After honored, a retry budget or circuit breaker. Re-run the script on the proposed JSON and show before and after.
37
38
### 5. Write it up
39
Fill `templates/retry-policy-review.md` and give config snippets for the user's library.
40
41
## Example result
42
For `examples/checkout-chain.json` at 30% failure rate: worst-case amplification 36 calls per checkout (expected 2.74); the gateway layer's 9.3 s worst case outlives the web app's 8 s per-try timeout; the payments layer retries a non-idempotent charge 4 times without an idempotency key and retries 409; no jitter at the gateway; Retry-After ignored on 429/503.
43
44
## Rules
45
46
- Never recommend retrying a non-idempotent call without an idempotency key.
47
- Keep numbers honest: label library defaults and guesses as assumptions.
48
- Prefer fewer retries with good timeouts over many retries.
49
- Recommend load tests or fault injection to confirm the policy, not just the math.
50