Background Job

Background Job Persona

Orchestrates robust background job implementation with TDD discipline, proper retry/discard strategies, comprehensive failure scenario testing, and production monitoring to ensure reliable async processing.

---

Phase 1: Job Design

Objective: Define job responsibilities, idempotency strategy, and error classification before writing code.

Steps:

1. Job Purpose — Define trigger conditions, input parameters, expected output/side effects, and criticality.
2. Idempotency — Design job to be safely re-runnable: use unique job keys, status checks, or sentinel timestamps.
3. Error Classification — Classify all anticipated errors:

• Transient (network timeouts, rate limits) → retry
• Permanent (invalid data, record not found) → discard
• Configuration (missing credentials) → alert

1. Queue & Timeout — Assign queue priority and set execution timeout.

HARD GATE — Job Design Complete:

• [ ] Purpose, trigger, input/output defined
• [ ] Idempotency strategy specified
• [ ] All errors classified as transient/permanent
• [ ] Queue and timeout values chosen

If gate fails: Clarify requirements before implementation.

---

Phase 2: TDD Implementation

Objective: Implement job logic under TDD discipline.

Steps:

1. Choose unit vs. integration test approach.
2. Write failing tests covering: successful execution, idempotency (run twice = same result), transient error raises, permanent error discards.
3. Confirm tests FAIL for the right reason (job not yet implemented).
4. Propose implementation approach and wait for explicit user approval.
5. Implement job using the structure shown in Phase 3 (retry/discard declarations included from the start); confirm tests PASS.
6. Run full test suite — confirm no regressions.

HARD GATE — Tests Pass:

• [ ] Tests exist and run
• [ ] Tests failed before implementation
• [ ] All tests pass after implementation
• [ ] Full suite green

Example job test skeleton (for OrderConfirmationEmailJob — see Phase 3 for the matching implementation):

# spec/jobs/order_confirmation_email_job_spec.rb
RSpec.describe OrderConfirmationEmailJob do
  let(:order) { create(:order, :completed) }

  it 'sends confirmation email' do
    expect(EmailService).to receive(:send_confirmation).with(order.id, order.customer_email, order.total)
    described_class.perform_now(order.id, order.customer_email, order.total)
  end

  it 'is idempotent' do
    expect(EmailService).to receive(:send_confirmation).once
    2.times { described_class.perform_now(order.id, order.customer_email, order.total) }
  end

  it 'raises on transient errors so retry triggers' do
    allow(EmailService).to receive(:send_confirmation).and_raise(EmailService::TimeoutError)
    expect { described_class.perform_now(order.id, order.customer_email, order.total) }.to raise_error(EmailService::TimeoutError)
  end

  it 'logs and re-raises on transient error' do
    allow(EmailService).to receive(:send_confirmation).and_raise(EmailService::TimeoutError)
    expect(Rails.logger).to receive(:error).with(/transient error/)
    expect { described_class.perform_now(order.id, order.customer_email, order.total) }
      .to raise_error(EmailService::TimeoutError)
  end

  it 'discards silently on permanent error' do
    allow(EmailService).to receive(:send_confirmation).and_raise(EmailService::InvalidEmailError)
    expect { described_class.perform_now(order.id, "bad", order.total) }.not_to raise_error
  end
end

---

Phase 3: Retry/Discard Configuration

Objective: Harden job for production with correct retry backoff, discard rules, timeouts, and monitoring hooks.

Steps:

1. Choose backend (Solid Queue for Rails 8+, Sidekiq for high scale) and configure worker concurrency.
2. Apply retry_on with exponential backoff and a capped attempt count (3–5) for every transient error class.
3. Apply discard_on for every permanent error class; log discards.
4. Set job execution timeout and queue timeout at the worker/config level.
5. Wire error tracking (e.g., Sentry) and metrics (e.g., StatsD/Datadog) in ApplicationJob callbacks.

Complete job implementation (matches the test skeleton in Phase 2):

# app/jobs/order_confirmation_email_job.rb
class OrderConfirmationEmailJob  e
    Rails.logger.error("[#{self.class}] transient error: #{e.message}")
    raise
  end
end

Solid Queue (Rails 8+) snippet:

# config/initializers/solid_queue.rb
SolidQueue.configure { |c| c.worker = { processes: 2, threads: 5, polling_interval: 1 } }

Sidekiq snippet:

# config/initializers/sidekiq.rb
Sidekiq.configure_server { |c| c.redis = { url: ENV['REDIS_URL'] } }

Monitoring hook in ApplicationJob:

class ApplicationJob 
- Purpose: 
- Idempotency strategy: 
- Error classification: transient () / permanent ()

## TDD
- Spec: 
- RED: 
- GREEN: 

## Retry Configuration
- retry_on: 
- discard_on: 
- Timeouts: 

## Failure Scenarios Tested
- Transient error → retries: ✓
- Permanent error → discards: ✓
- Idempotency → no duplicate side effects: ✓
- Timeout handling: ✓

## Monitoring
- Metrics: 
- Error tracking: 
- Queue depth alerts: 

---

Integration

| Predecessor | This Persona | Successor | |-------------|--------------|----------| | load-context | background-job | code-review | | tdd | background-job | quality | | None (standalone) | background-job | PR submission |

Use implement-background-job alone if the job design is already decided and you only need to implement the job class and specs.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: igmarin
• Source: igmarin/rails-agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.