home / skills / makfly / superpowers-symfony / messenger-retry-failures

messenger-retry-failures skill

safe

This skill helps implement resilient Symfony async workflows with idempotent handlers, configurable retries, and observability to manage messenger failures.

npx playbooks add skill makfly/superpowers-symfony --skill messenger-retry-failures

Review the files below or copy the command above to add this skill to your agents.

Files (2)

SKILL.md

1.1 KB

---

name: symfony:messenger-retry-failures
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash
  - Glob
  - Grep
description: Implement resilient Symfony async workflows with idempotency, retries, and operational visibility. Use for messenger retry failures tasks.
---

# Messenger Retry Failures (Symfony)

## Use when
- Implementing asynchronous workflows with Messenger/Scheduler/Cache.
- Stabilizing retries and failure transports.

## Default workflow
1. Define async contract and delivery semantics.
2. Implement idempotent handlers and routing strategy.
2. Configure retries, failure transport, and observability.
2. Validate success/failure replay scenarios.

## Guardrails
- Assume at-least-once delivery, not exactly-once.
- Keep handlers deterministic and side-effect aware.
- Surface poison-message handling strategy.

## Progressive disclosure
- Use this file for execution posture and risk controls.
- Open references when deep implementation details are needed.

## Output contract
- Async config/handlers updated.
- Retry/failure policy decisions.
- Operational validation evidence.

## References
- `reference.md`
- `docs/complexity-tiers.md`

Overview

This skill implements resilient Symfony Messenger async workflows focused on idempotency, retries, and operational visibility. It provides a practical execution posture for handling retry failures and stabilizing failure transports. Use it to codify retry policies, failure routing, and evidence for operational validation.

How this skill works

The skill inspects and updates Messenger configuration, handler implementations, and retry/failure transport settings to enforce at-least-once delivery assumptions. It guides creation of idempotent handlers, deterministic routing strategies, and clear poison-message handling. The skill outputs updated async config, documented retry/failure policy decisions, and operational validation artifacts (logs, replay tests, metrics).

When to use it

When building or stabilizing asynchronous workflows with Symfony Messenger and Scheduler
When delivery retries are causing duplicate side effects or unexpected failures
When you need clear failure transport and poison-message handling policies
During production readiness reviews where operational visibility and evidence are required
When implementing or validating idempotency across async handlers

Best practices

Design handlers for idempotency and deterministic behavior under at-least-once delivery
Configure retry/backoff and a dedicated failure transport rather than silent drops
Surface poison-message strategies early: quarantining, alerting, and replay policies
Validate replay and failure scenarios with tests and operational runbooks
Emit structured logs and metrics for retries, failures, and replay attempts

Example use cases

Stabilize a job processing pipeline where retries cause duplicate database writes
Implement a failure transport that quarantines messages for manual triage
Add replay tests and metrics to prove safe reprocessing of failed messages
Define and deploy backoff and max-retry policies for third-party API calls
Create operational runbooks that describe how to handle poison messages and replays

FAQ

Does this assume exactly-once delivery?

No. The skill assumes at-least-once delivery and focuses on idempotency and deterministic handlers.

What outputs will I get?

You will get updated async config, documented retry/failure policy decisions, and operational validation evidence such as tests, logs, and metrics.

How should I handle poison messages?

Quarantine them in a failure transport, alert the team, and provide a replay path with safeguards and audit trails.