---
title: "Design a fallback path for a flaky tool"
description: "Classify how a dependency fails, decide what retries and what escalates, and write the runbook before the tool goes down at the wrong moment."
canonical: "https://www.diginomads.win/prompts/design-a-fallback-path"
source: "content/pages/prompts/design-a-fallback-path.md"
updatedAt: "2026-11-10"
---

## Copy-ready prompt

~~~text
You are designing a fallback for a workflow that depends on [TOOL].

Inputs:
- Workflow: [WORKFLOW]
- Observed and likely failures: [FAILURES]
- Constraints: [CONSTRAINTS]

Work in this order:
1. Classify each failure: transient (retry likely works), degraded (slow or partial), hard down, or silent wrong output.
2. For each class, define: detection signal, retry policy with a cap, fallback, human escalation, and the data risk of each option.
3. Write what the user or client sees at each stage. “Internal error” is not a status.
4. Write a runbook: the commands or links a person needs, in order, with the decision point for stopping.
5. Define how to test the fallback with a simulated failure. Do not wait for a real outage to find out.
6. Name what should not be automated, and why.

Rules:
- Do not retry a non-idempotent write without an idempotency key or a manual check.
- Do not silently switch to a fallback that changes the meaning of the output. Label it.
- Do not invent a status page, an API limit or a support channel. Mark unknown values.
- Keep secrets out of logs, prompts and the runbook.
~~~

**Use when:** A workflow depends on an API, a model, a queue or a network, and you need to know what happens when it is slow, wrong or down.

**Output contract:** A failure classification, detection signals, retry and fallback rules, a human escalation path and a runbook you can test.

**Inputs you need:**

- The workflow and the tool it depends on
- How the tool fails: timeouts, errors, rate limits, wrong output
- What the user or client sees when it fails

| Variable | What to put there |
|---|---|
| [TOOL] | The dependency and what you use it for: model inference, payments, email, storage, search, a scheduling API. |
| [WORKFLOW] | The steps before and after the tool call. The fallback has to preserve the contract at the boundary. |
| [FAILURES] | What you have seen and what you fear: 429s, timeouts, partial writes, wrong model output, expired tokens. |
| [CONSTRAINTS] | Latency budget, cost ceiling, data residency, client promise. These decide which fallback is acceptable. |

## How to use it

1. List the failures before the fallbacks. A fallback for the wrong failure is a new failure.
2. Define the detection signal first. If you cannot tell a slow call from a wrong answer, you cannot route it.
3. Cap retries and make them visible. Silent retries turn an incident into a mystery.
4. Test by injecting the failure in a staging environment. A runbook that has never been run is a guess.

## Guardrails

- A silent wrong output is treated as a failure, not a success.
- Retries are capped and never applied to a non-idempotent write without a key.
- Every fallback is labelled in the output.
- The runbook contains no secret and has a named owner.

## Variations

### If the dependency is a model provider

Add a second provider only if you have tested the prompt on it. A fallback model that follows instructions differently can change the output more than an outage.

### If the dependency is a payment or email service

Add a reconciliation step and a human check before resending. A duplicate charge or email is worse than a delay.

## Why design the failure before the feature

A workflow that works on a good day is a demo. A workflow that fails visibly, retries safely and escalates to a person is a system. The difference is designed before the first outage, not during it.

The most dangerous failure is not the hard down. It is the silent wrong output: a plausible answer from a degraded model, a partial write that looks complete, an email that says it sent. Those failures need a detection signal, not just a retry.

## What good looks like

The classification is short and specific. “Timeout after 10 seconds” is a signal; “the API is flaky” is a mood. The fallback is labelled in the output so a reader knows which path produced it.

The runbook fits on one page and names the person who decides to stop. If it needs a meeting to interpret, it is not a runbook.

## Adapt it to your work

For a client workflow, agree the failure behaviour in writing before launch: what the client sees, who is called, and what is not retried. For a solo workflow, the runbook can be a note to yourself with the exact commands.

## Failure modes

- **Retry everything.** Retries amplify a rate limit and can duplicate a write.
- **Fallback changes the meaning.** A cheaper model or a cached answer is not the same product. Label it.
- **No test.** The first real outage is a bad time to discover the fallback path is broken.

## Related templates

- [Audit an agent workflow before you automate it](/prompts/audit-an-agent-workflow)
- [Reproduce a bug before fixing it](/prompts/reproduce-a-bug)
- [The agent-ops skill pack](/skills/agent-ops)

## Structured data

```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "name": "Design a fallback path for a flaky tool",
  "url": "https://www.diginomads.win/prompts/design-a-fallback-path",
  "description": "Classify how a dependency fails, decide what retries and what escalates, and write the runbook before the tool goes down at the wrong moment.",
  "isPartOf": {
    "@type": "WebSite",
    "name": "DigiNomads",
    "url": "https://www.diginomads.win/"
  }
}
```