background-jobslisted
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