# Implement Background Job

> >

- **Type:** Skill
- **Install:** `agentstack add skill-igmarin-rails-agent-skills-implement-background-job`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [igmarin](https://agentstack.voostack.com/s/igmarin)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [igmarin](https://github.com/igmarin)
- **Source:** https://github.com/igmarin/rails-agent-skills/tree/main/skills/infrastructure/implement-background-job

## Install

```sh
agentstack add skill-igmarin-rails-agent-skills-implement-background-job
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Implement Background Job

Use this skill when the task is to add, configure, or review background jobs in a Rails application.

## HARD-GATE

```text
EVERY job MUST have its test written and validated BEFORE implementation:
  1. Write the job spec (idempotency, retry, error handling)
  2. Run the spec — verify it fails
  3. ONLY THEN write the job class

The authoritative perform contract — EVERY perform method does exactly three things:
  1. Load the record from the passed ID
  2. Guard for idempotency / permanent no-op conditions
  3. Delegate the side effect or orchestration to a service object

If perform needs more than that, extract a service.
EVERY job that performs a side effect (charge, email, API call) MUST have
an idempotency check BEFORE the side effect.
```

## Core Rules

| Aspect | Rule |
|--------|------|
| Arguments | Pass IDs, not objects |
| Retries | `retry_on` (explicit `attempts:`) for transient; `discard_on` for permanent errors |
| Backend (Rails 8) | Solid Queue (database-backed, no Redis) |
| Backend (Rails 7) | Sidekiq + Redis for high throughput |
| Recurring | `config/recurring.yml` (Solid Queue) or cron/sidekiq-cron |
| Anti-patterns | No ActiveRecord objects as args; no `:inline`/`:async` in production; no business logic in `perform` |

## Core Process

1. Write the job spec first — idempotency, retry, and error handling — and run it to confirm it fails.
2. Write the job class following the perform contract in HARD-GATE.
3. Add `retry_on` with explicit `attempts:` limit and `discard_on` for at least one permanent error.
4. Run the full test suite.
5. Enqueue or perform the job twice — confirm the second run is a no-op.
6. For recurring jobs, define them in `config/recurring.yml` (Rails 8) or the chosen scheduler config.

## Extended Resources

**Rails 8 vs Rails 7**
| Aspect | Rails 7 and earlier | Rails 8 |
|--------|---------------------|---------|
| Default | No default; set `queue_adapter` (often Sidekiq) | **Solid Queue** (database-backed) |
| Dev/test | `:async` or `:inline` | Same |
| Recurring | External (cron, sidekiq-cron) | `config/recurring.yml` |
| Dashboard | Third-party (Sidekiq Web) | **Mission Control Jobs** |

**Examples**

**Thin job with idempotency and retry:**
```ruby
class SendInvoiceReminderJob < ApplicationJob
  queue_as :default
  retry_on Net::OpenTimeout, wait: :polynomially_longer, attempts: 5
  discard_on ActiveRecord::RecordNotFound

  def perform(invoice_id)
    invoice = Invoice.find(invoice_id)
    return if invoice.reminder_sent_at?

    InvoiceReminders::Send.call(invoice:)
  end
end
```

**Service owns the side effect and state update:**
```ruby
module InvoiceReminders
  class Send
    def self.call(invoice:)
      InvoiceMailer.overdue(invoice).deliver_now
      invoice.update!(reminder_sent_at: Time.current)
    end
  end
end
```

- [BACKENDS.md](./BACKENDS.md) — Solid Queue vs Sidekiq setup, configuration details, and Redis requirements.
Load these files only when their specific content is needed:

- **[assets/job_patterns.md](assets/job_patterns.md)** — Use when implementing multi-step orchestration or batch job patterns
- **[assets/retry_examples.md](assets/retry_examples.md)** — Use when configuring `retry_on`/`discard_on` for specific error classes beyond the basic patterns above

## Output Checklist

- [ ] Backend decision stated (Rails version/scale → Solid Queue or Sidekiq)
- [ ] Job spec shown first; command run; confirms failure before implementation
- [ ] `perform` receives IDs, loads record, guards idempotency, delegates to service
- [ ] `retry_on` with `attempts:` limit and `discard_on` for permanent error
- [ ] Double-run verification confirms second run is a no-op
- [ ] Recurring job (if any) defined in `config/recurring.yml` or scheduler config
- [ ] If ops docs requested: record backend, retry, recurring schedule, and idempotency decisions in `process_log.md`

## Integration

| Skill | When to chain |
|-------|---------------|
| **review-migration** | Solid Queue uses DB tables; add migrations safely |
| **security-check** | Jobs receive serialized input; validate like any entry point |
| **write-tests** | TDD gate: write job spec before implementation; use `perform_enqueued_jobs` |
| **create-service-object** | Keep `perform` thin; call service objects for business logic |

## Source & license

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

- **Author:** [igmarin](https://github.com/igmarin)
- **Source:** [igmarin/rails-agent-skills](https://github.com/igmarin/rails-agent-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-igmarin-rails-agent-skills-implement-background-job
- Seller: https://agentstack.voostack.com/s/igmarin
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.