OneLinersCommand workbench
AI
Back to skills
SKILL.md

Asynchronous job design reviewer

An evidence-first workflow to design bounded background work with retries, idempotency, cancellation, and observability.

Revision
2
Verified
2026-10-20
Save or explore
Save to collectionCreate a collection in the sidebar first.

Compatibility and paths

Codexskills/async-job-design/SKILL.md
Claude Code.claude/skills/async-job-design/SKILL.md
VS Code.github/skills/async-job-design/SKILL.md

Trust and provenance

Curated record reviewed 2026-10-20. Results still depend on the supplied context and target environment.

Generated assetReady to copy or download
---
name: async-job-design
description: Reviews background-job state and external side-effect boundaries under duplicate delivery, crashes, deadlines and cancellation. Use before shipping a queue consumer or redrive path; specify durable evidence and reconciliation instead of claiming exactly-once execution.
license: CC-BY-4.0
compatibility: Reviews redacted contracts and synthetic cases offline. Live API writes, queue execution, webhooks and external side effects need separate scoped authorization.
metadata:
  author: oneliners
  version: "2.0.0"
---

# Asynchronous job design reviewer

## Start with the effect, not the queue brand
Name the business effect, authenticated tenant/account, acceptance contract, durable job identity and completion evidence. Record delivery semantics, visibility/lease behavior, retry/deadline budgets, payload/schema version, dependency ownership and operator recovery policy. An HTTP202 response means acceptance under the API contract, not completed work. A process-local task or promise is not durable background execution. Ask what happens if the process exits immediately after acceptance.

## Draw the crash boundaries explicitly
List durable enqueue, claim/lease, side-effect dispatch, downstream acceptance, local result commit and queue acknowledgement separately. For each boundary ask what a duplicate worker sees and whether another attempt could repeat the effect. A lock or job deduplication row may prevent some duplicate processing but cannot erase uncertainty after an external provider accepted a request. Use a stable tenant-scoped business effect key only where downstream retention/payload/account semantics are verified. CloudEvents source/id can identify a duplicate event; they are not an exactly-once effect guarantee.

## Worked uncertain email outcome
The sender/provider is fictional. No provider feature is assumed beyond the explicit supplied contract, which is itself not yet verified for a real integration. No personal address or message body is needed to review this boundary.

```json
{
  "provenance": "synthetic lifecycle and provider assumptions; no email sent or queue contacted",
  "job": "job-42",
  "tenant": "tenant-A",
  "operation": "send-summary",
  "stableEffectKey": "tenant-A:job-42:send-summary:v1",
  "delivery": "at least once; duplicate work can occur",
  "policy": {
    "deadlineSeconds": 300,
    "maxAttempts": 3,
    "cancelRequested": false
  },
  "downstream": {
    "idempotencySupported": true,
    "documentedRetentionSeconds": 86400,
    "scope": "same provider account, operation and identical payload",
    "actualProviderVerified": false
  },
  "recovery": {
    "ageSeconds": 120,
    "attempt": 2,
    "externalOutcome": "UNKNOWN",
    "localStatus": "running",
    "payloadSame": true
  },
  "trace": [
    "durably enqueue job42",
    "worker claims attempt1",
    "provider accepts effect; receipt not durably recorded locally",
    "worker crashes before local success/queue ack",
    "message is delivered again"
  ]
}
```

## Recovery decision and state contract
Problem: the crash occurs AFTER external acceptance but BEFORE durable local success/queue acknowledgement. localStatus=running does not prove the email was not sent. Redelivering the job or deduplicating only job insertion does not guarantee exactly-once external effects.

Under the supplied fictional provider contract, recovery at120s/attempt2 is within the300s deadline,3-attempt budget and86400s key retention, with identical payload/account/operation. Candidate plan: reuse tenant-A:job-42:send-summary:v1 and reconcile the provider's existing result before recording local completion/ack. This is conditional on real downstream idempotency semantics being verified; actualProviderVerified=false means implementation approval stays on HOLD, not a live retry instruction. Never generate a new random effect key per attempt.

Durable boundaries: accept/enqueue atomically or via a reviewed outbox; claim work with bounded leases; commit the effect receipt and terminal status so a redelivery can recognize completion; acknowledge only after the durable result boundary. A local database transaction cannot by itself atomically commit an unrelated provider's email send. Preserve UNKNOWN external outcome rather than relabeling it failed/unsent.

Late/manual redrive at48h exceeds the ordinary deadline AND the supplied downstream idempotency window. Stop and reconcile with the owner/provider evidence; creating a new job/key or extending a deadline does not restore the expired guarantee. If the provider has no usable idempotency/reconciliation contract, an uncertain send requires operator review, not blind retries.

Cancellation: queued/not-started may become cancelled without sending. Running/UNKNOWN can only record cancellation requested and reconcile; it cannot truthfully promise that an accepted email was recalled. Confirmed completed work records the existing result without resending. Define separate expired/failed/needs-reconciliation outcomes instead of forcing every interruption into retryable failure.

Signals: job/tenant-safe pseudonymous correlation, attempt, age/deadline, lease owner, durable status, effect-key hash and redacted receipt reference. Do not retain email bodies, credentials or full personal data in an error report. No provider call, queue ack, cancellation or deployment was executed; this is a reviewed state/effect contract.

## Required failure-injection cases
1. Crash before durable enqueue: acceptance must not claim a durable job exists. Define client retry/idempotency behavior at the enqueue transaction.
2. Crash after enqueue but before worker dispatch: a redelivery should claim the same job under the agreed lease/attempt policy, not invent a second business request.
3. Crash after downstream acceptance but before local receipt: exercise the exact uncertain path above. The test double may model key reuse, but it cannot prove the vendor's implementation or retention.
4. Confirm an existing downstream result: commit that receipt/status without resending. Preserve evidence of the prior attempt and idempotency scope.
5. Expire the attempt/deadline or effect-key retention, change the payload, or remove downstream deduplication support: stop/reconcile instead of silently treating uncertainty as a new unsent request.
6. Request cancellation in queued and running states separately. Ensure an already performed effect is not reported as undone. Do not test this by sending real mail to users.

## Output and release gate
Return state-transition table, durable owner for every transition, crash/replay matrix, retry classes/budgets, stable-key scope and retention, cancellation semantics, reconciliation UX and minimal observability. Distinguish proposed invariants from verified database/queue/provider behavior. Require isolated fixture tests plus separately authorized integration evidence before approval; do not mark HOLD conditions green because a local simulation passes. Never drain/replay production queues, alter a schedule or send a compensating message from this review. [CloudEvents identity semantics](https://github.com/cloudevents/spec/blob/v1.0.2/cloudevents/spec.md#id) help deduplication design but do not supply delivery or effect transactions.

Real example

Input

Review this synthetic crash boundary; do not send or retry an external effect.

{
  "provenance": "synthetic lifecycle and provider assumptions; no email sent or queue contacted",
  "job": "job-42",
  "tenant": "tenant-A",
  "operation": "send-summary",
  "stableEffectKey": "tenant-A:job-42:send-summary:v1",
  "delivery": "at least once; duplicate work can occur",
  "policy": {
    "deadlineSeconds": 300,
    "maxAttempts": 3,
    "cancelRequested": false
  },
  "downstream": {
    "idempotencySupported": true,
    "documentedRetentionSeconds": 86400,
    "scope": "same provider account, operation and identical payload",
    "actualProviderVerified": false
  },
  "recovery": {
    "ageSeconds": 120,
    "attempt": 2,
    "externalOutcome": "UNKNOWN",
    "localStatus": "running",
    "payloadSame": true
  },
  "trace": [
    "durably enqueue job42",
    "worker claims attempt1",
    "provider accepts effect; receipt not durably recorded locally",
    "worker crashes before local success/queue ack",
    "message is delivered again"
  ]
}

Expected result

Problem: the crash occurs AFTER external acceptance but BEFORE durable local success/queue acknowledgement. localStatus=running does not prove the email was not sent. Redelivering the job or deduplicating only job insertion does not guarantee exactly-once external effects.

Under the supplied fictional provider contract, recovery at120s/attempt2 is within the300s deadline,3-attempt budget and86400s key retention, with identical payload/account/operation. Candidate plan: reuse tenant-A:job-42:send-summary:v1 and reconcile the provider's existing result before recording local completion/ack. This is conditional on real downstream idempotency semantics being verified; actualProviderVerified=false means implementation approval stays on HOLD, not a live retry instruction. Never generate a new random effect key per attempt.

Durable boundaries: accept/enqueue atomically or via a reviewed outbox; claim work with bounded leases; commit the effect receipt and terminal status so a redelivery can recognize completion; acknowledge only after the durable result boundary. A local database transaction cannot by itself atomically commit an unrelated provider's email send. Preserve UNKNOWN external outcome rather than relabeling it failed/unsent.

Late/manual redrive at48h exceeds the ordinary deadline AND the supplied downstream idempotency window. Stop and reconcile with the owner/provider evidence; creating a new job/key or extending a deadline does not restore the expired guarantee. If the provider has no usable idempotency/reconciliation contract, an uncertain send requires operator review, not blind retries.

Cancellation: queued/not-started may become cancelled without sending. Running/UNKNOWN can only record cancellation requested and reconcile; it cannot truthfully promise that an accepted email was recalled. Confirmed completed work records the existing result without resending. Define separate expired/failed/needs-reconciliation outcomes instead of forcing every interruption into retryable failure.

Signals: job/tenant-safe pseudonymous correlation, attempt, age/deadline, lease owner, durable status, effect-key hash and redacted receipt reference. Do not retain email bodies, credentials or full personal data in an error report. No provider call, queue ack, cancellation or deployment was executed; this is a reviewed state/effect contract.

Source evidence

Agent Skills specificationofficialCloudEvents specificationofficialCloudEvents v1.0.2 event identityofficial