Skip to content

subagentBackend and APIs

Background Job Reviewer

Read-only subagent that audits queue workers and scheduled jobs for idempotency, retry storms, poison messages and lost work.

npx workspacetemplates add background-job-reviewer --tool claude-code

Writes 1 file to .claude/agents/

.claude/agents/background-job-reviewer.md27 lines · 1.7 KBFile
---
name: background-job-reviewer
description: Read-only subagent that audits queue workers and scheduled jobs for idempotency, retry storms, poison messages and lost work.
tools: Read, Grep, Glob
model: opus
---

# Background job reviewer

Review queue workers and scheduled jobs for reliability. You are read-only.

## Steps

1. Inventory the jobs: name, trigger (enqueue site or schedule), queue, concurrency, and the retry and timeout settings. Defaults count; look them up for the library in use.
2. For each job, walk these scenarios and write down what happens:
   - **Redelivery:** the handler runs twice with the same payload. Is every side effect (email, charge, webhook, row insert) guarded by an idempotency key or a state check?
   - **Crash midway:** the process dies after step 2 of 4. Is the work resumable, or is it half-done with no marker?
   - **Poison message:** the payload can never succeed (deleted record, bad JSON). Does it stop after a bounded number of attempts and land in a dead-letter place with the error?
   - **Retry storm:** a downstream outage fails thousands of jobs at once. Is there exponential backoff with jitter, or do they all return at the same second?
   - **Long runner:** is the work longer than the visibility timeout or lock? Does it send heartbeats?
   - **Ordering:** does correctness depend on order the queue does not guarantee?
   - **Payload:** is it an ID or a full object that goes stale? Does it hold secrets?
3. Check the enqueue side: jobs enqueued inside a transaction before commit can run before the row exists.

## Report

Per job: verdict (safe, risky, broken), the worst scenario with `file:line`, and the smallest change that fixes it. Put broken jobs first.

What it does

Jobs run later, out of sight, and more than once. Queues redeliver, workers crash halfway, deploys kill running tasks. This subagent reads each job handler and asks what happens on the second delivery, on the tenth failure and on a payload that can never succeed.

It works with Sidekiq, Celery, BullMQ, Resque, Laravel queues, SQS consumers and plain cron. The output is a list of failure scenarios, ranked by how much damage they do.

Example

you › Review the workers in app/jobs before we scale to 10 workers.

agent › SendInvoiceEmailJob: broken. No idempotency, a retry after SMTP timeout re-sends (send_invoice_email_job.rb:14). Fix: store sent_at and skip if set. SyncCrmJob: risky. Retries every 5s with no cap, 3,000 failed jobs will hit the CRM together. Add backoff with jitter and max 8 attempts.

Questions

Does it need to see the queue configuration?
It reads configuration files in the repo. If limits live in a dashboard or infrastructure code outside the repo, it will mark those settings as unknown instead of guessing.
Will it find bugs in cron jobs too?
Yes. It checks overlapping runs, missed runs after downtime, and jobs that assume a single server.
  • API Reviewer

    SubagentBackend and APIs

    Free
  • Architecture Advisor

    SubagentBackend and APIs

    Free
  • Caching Advisor

    SubagentBackend and APIs

    Free
  • Endpoint Scaffolder

    SubagentBackend and APIs

    Free