← ClaudeAtlas

background-jobslisted

Use when a ticket moves work off the request path or adds asynchronous processing — a job queue, a worker, an outbox, "send the email later", "process uploads in the background", retries for a failed job — and the job must be idempotent, observable, bounded, and safe to run twice. Invoke for any queue, worker, or deferred-processing change.
tmj-90/gaffer · ★ 1 · AI & Automation · score 70
Install: claude install-skill tmj-90/gaffer
# Add a background job A background job is a promise the request made and a worker must keep, later, maybe on another machine, maybe twice. Queues deliver at least once: a worker that crashes, times out or pauses past its visibility window gets its job handed to another worker while it may still finish. Design for redelivery, overlap and partial failure first. ## Steps 1. **Use the repo's job system.** A queue library (BullMQ, Celery, Sidekiq, River, Hangfire, Quartz), a database-backed queue or outbox, or the platform queue (SQS, Pub/Sub). Call `search_lore` for it and its retry defaults; never add a second system for one job. Time-driven work belongs to the `scheduled-jobs` skill. 2. **Keep the payload small and versioned.** Identifiers (`orderId`) and a schema version, never whole objects that will be stale when the job runs. Validate the payload at the worker like any untrusted input; an invalid payload is a permanent failure. 3. **Enqueue atomically with the state change.** Write the row and the job in one transaction (a jobs/outbox table in the same database, drained by a relay), or enqueue only after commit. Enqueue-before-commit creates jobs for rows that rolled back; enqueue-after-commit without an outbox loses the job if the process dies in between. An outbox relay either runs as one instance or claims rows with `FOR UPDATE SKIP LOCKED`. 4. **Make the handler idempotent.** Redelivery is normal. Key the effect on the job id or a