Retry Policy Specification Prompt

This prompt is designed for platform teams and infrastructure engineers who need to produce precise, unambiguous documentation of webhook retry behavior. The job-to-be-done is converting internal retry logic—often scattered across config files, queue worker code, and on-call runbooks—into a single, consumer-facing specification that integration engineers can rely on to build resilient receivers. The ideal user is a backend engineer or technical writer who understands the system's actual retry implementation but needs help structuring it into a complete, readable document that covers schedules, backoff strategies, maximum attempts, timeouts, jitter, and failure destinations.

Use this prompt when you have access to the ground truth about your system's retry behavior—whether from source code, configuration, or architecture decisions. The prompt requires several concrete inputs to be effective: the retry schedule (intervals between attempts), the backoff strategy (linear, exponential, or custom), the maximum number of attempts before giving up, any jitter configuration, the total timeout window, and the dead-letter queue or failure destination where events go after retries are exhausted. If you cannot provide these specifics, the prompt will produce vague documentation that fails the primary goal of giving consumers enough detail to implement correct error handling and idempotency on their side.

Do not use this prompt when you are still designing the retry policy rather than documenting an existing one. It is not a design tool—it assumes the policy is already decided and needs to be communicated. Avoid using it for systems where retry behavior varies unpredictably per event type or tenant without a clear specification; in those cases, you need a different approach that documents the variability rules rather than a single policy. After generating the documentation, always validate it against the actual implementation by running integration tests that simulate each retry attempt, timeout, and dead-letter scenario. The output should be reviewed by both the engineering team that owns the delivery pipeline and a sample of API consumers who can confirm the documentation answers their operational questions.

This prompt template is designed to produce a comprehensive retry policy document for your webhook system. It takes your specific operational constraints—such as maximum attempts, backoff strategy, and failure destinations—and generates a specification that covers the retry schedule, jitter, timeouts, and dead-letter queue behavior. The output is intended for both internal platform documentation and external consumer-facing guides, ensuring that integration engineers understand exactly how your system handles delivery failures.

codeCopy
You are a technical documentation engineer for a platform team. Your task is to produce a complete, unambiguous specification for a webhook retry policy based on the provided parameters.

## Input Parameters
- **Maximum Attempts:** [MAX_ATTEMPTS]
- **Initial Retry Delay:** [INITIAL_DELAY] (e.g., 1s, 30s, 5m)
- **Backoff Strategy:** [BACKOFF_STRATEGY] (e.g., exponential, linear, fixed)
- **Backoff Multiplier:** [BACKOFF_MULTIPLIER] (if applicable)
- **Maximum Delay Cap:** [MAX_DELAY_CAP] (e.g., 1h)
- **Jitter Strategy:** [JITTER_STRATEGY] (e.g., full, equal, none)
- **Request Timeout:** [REQUEST_TIMEOUT] (per delivery attempt)
- **Failure Destination:** [FAILURE_DESTINATION] (e.g., dead-letter queue, S3 bucket, log-only)
- **Success Criteria:** [SUCCESS_CRITERIA] (e.g., HTTP 2xx, specific status codes)
- **Idempotency Key Header:** [IDEMPOTENCY_KEY_HEADER]
- **Delivery Ordering Guarantee:** [ORDERING_GUARANTEE] (e.g., best-effort, FIFO per endpoint, none)

## Output Schema
Generate a specification document with the following sections. Use the exact headers provided.

### 1. Overview
A plain-language summary of the retry policy, its purpose, and when it applies.

### 2. Retry Schedule
A detailed description of the retry timeline. Include a table with columns for Attempt Number, Delay Before Attempt, and Cumulative Time. Calculate exact values based on the input parameters.

### 3. Backoff and Jitter
Explain the backoff algorithm and jitter strategy in detail. Provide a formula or pseudocode representation of the delay calculation. Explain how jitter is applied to prevent thundering herd problems.

### 4. Timeout and Connection Behavior
Specify the per-request timeout, how connection errors vs. read timeouts are handled, and whether a timeout counts as an attempt.

### 5. Failure Destination and Dead-Letter Queue
Describe what happens after [MAX_ATTEMPTS] are exhausted. Detail the format of the dead-lettered event, its storage location, retention period, and how consumers can inspect or replay failed events.

### 6. Idempotency and Deduplication
Explain how the [IDEMPOTENCY_KEY_HEADER] header is used across retries. Specify the deduplication window and how consumers should handle duplicate deliveries.

### 7. Ordering and Concurrency
Describe the [ORDERING_GUARANTEE] during retries. Explain whether retries for one event block subsequent events for the same endpoint.

### 8. Monitoring and Alerting
Recommend what metrics and logs consumers should monitor (e.g., retry count spikes, DLQ growth) and what alerts the platform triggers internally.

## Constraints
- Use exact numeric values derived from the input parameters. Do not use placeholders in the output.
- If a parameter is marked "none" or "N/A", explicitly state that the feature is not supported.
- Do not invent features or guarantees not specified in the input parameters.
- Write for an audience of integration engineers who need to build against this contract.

To adapt this template, replace each bracketed placeholder with your platform's specific values. For the backoff strategy, ensure you provide enough detail for the model to calculate an exact schedule—for example, if using exponential backoff with a multiplier of 2 and an initial delay of 1 second, the model should produce a table showing 1s, 2s, 4s, 8s, etc. After generating the specification, validate the output by checking that all numeric values in the retry schedule table are mathematically consistent with the input parameters. For high-reliability systems where this documentation becomes a contractual part of your API, have a senior engineer review the generated specification before publication.

The retry policy specification prompt is designed to be called programmatically as part of a documentation generation pipeline, not as a one-off chat interaction. In a typical implementation, a platform team triggers this prompt when a new webhook event type is registered or when an existing retry policy is modified. The prompt receives structured inputs—such as the event type name, target delivery SLA, and any existing policy fragments—and returns a complete retry policy document section. The output should be treated as a draft that requires human review before publication, because retry policies directly affect consumer reliability expectations and infrastructure load.

To integrate this prompt into an application, wrap it in a function that accepts a RetryPolicyInput schema with fields like event_type, delivery_sla_seconds, max_attempts, backoff_strategy (enum: exponential, linear, constant), jitter_enabled, timeout_per_attempt_ms, and dead_letter_queue_name. Before calling the model, validate that all required fields are present and that numeric values fall within acceptable ranges (e.g., max_attempts between 1 and 50). After receiving the model response, run a structured validation pass: check that the output contains all required sections (retry schedule, backoff strategy, maximum attempts, failure destination, idempotency guidance), that any mentioned timeout values match the input parameters, and that the dead-letter queue reference is not a placeholder. If validation fails, retry the prompt once with a more explicit [CONSTRAINTS] block that lists the missing sections. Log every generation attempt—including input parameters, model version, raw output, validation results, and final published text—so that future policy changes can be audited.

For high-reliability platforms, add a human approval step before the generated retry policy goes live. Route the validated output to a review queue where an engineer confirms that the backoff intervals won't overwhelm downstream consumers, that jitter is correctly specified, and that the dead-letter queue retention period aligns with operational runbooks. Avoid wiring this prompt directly into a CI/CD pipeline without a review gate; a malformed retry policy in production documentation can cause integration partners to implement incorrect retry logic, leading to thundering herd problems or missed deliveries. Pair this prompt with the webhook delivery guarantee documentation prompt and the idempotency key handling prompt to ensure consistency across all consumer-facing reliability documentation.