queue-system

name	queue-system
description	Use when creating, updating, reviewing, or debugging background jobs, queues, workers, async processing, retries, delayed jobs, scheduled jobs, idempotency, or dead-letter handling.

Queue System

Use this skill for safe background jobs and async processing.

Rules

• Follow the project’s existing queue/worker pattern.
• Do not add a new queue library, worker system, scheduler, or broker unless already used or explicitly requested.
• Move slow, heavy, retryable, or failure-prone work out of request paths when appropriate.
• Keep job payloads minimal; prefer IDs over full objects.
• Workers should fetch fresh data from the source of truth.
• Make jobs idempotent when retries or duplicate delivery are possible.
• Separate retryable and non-retryable failures.
• Use existing retry, timeout, concurrency, and failure handling patterns.
• Log job start, success, and failure with safe context.
• Do not log secrets, tokens, private payloads, or sensitive data.
• Preserve existing response, error, logging, and test patterns.
• Avoid unrelated refactors.

Inspect First

Before changing queue code, check existing patterns for:

• queue library or broker
• worker structure
• job names/types
• enqueue helper
• retry/backoff settings
• idempotency handling
• failure/dead-letter handling
• scheduled/delayed jobs
• logging and monitoring
• graceful shutdown
• test style

Implementation Checklist

• Identify the job type and purpose.
• Reuse existing queue and worker helpers.
• Pass only required IDs and safe metadata.
• Add an idempotency key when duplicate processing is possible.
• Configure retry/backoff using existing project defaults.
• Avoid retrying invalid input or permission failures.
• Add timeout or cancellation handling if the job can hang.
• Ensure worker fetches fresh data before acting.
• Handle success, retryable failure, and final failure.
• Add or update relevant tests.

Idempotency Rules

• A retried job must not duplicate side effects.
• Duplicate jobs should be skipped or safely reused.
• Payment, notification, webhook, inventory, and export jobs must be repeat-safe.
• Use existing unique keys, job IDs, processed-event records, or database constraints.
• Apply side effects only once.

Failure Handling

• Retry temporary failures such as network errors, provider timeouts, or rate limits.
• Do not retry permanent failures such as invalid payloads, missing required data, or permission errors.
• After max retries, mark the job failed using the project’s existing pattern.
• Use dead-letter/failure records if supported.
• Do not hide failed jobs silently.
• Make manual retry safe when the project supports it.

Worker Rules

• Workers should be safe to run more than once.
• Workers should support graceful shutdown if the project has that pattern.
• Concurrency must match the workload and provider limits.
• Long-running jobs should report progress only if the project supports it.
• Avoid unbounded loops, unbounded memory use, and large payloads.
• Do not block the queue with one slow job if the project has a way to isolate job types.

Security Rules

• Do not trust job payloads blindly.
• Re-check authorization or ownership when the job affects user data.
• Do not put secrets in job payloads.
• Do not log sensitive payload data.
• For tenant or organization data, include and verify scope safely.
• Ensure background jobs cannot act on another user’s resources.

Tests

Cover relevant paths:

• job enqueued
• worker processes job
• minimal payload used
• idempotency prevents duplicate side effects
• retryable failure retries
• non-retryable failure stops
• final failure is recorded
• worker fetches fresh data
• sensitive data is not logged