Cron Scheduling Stinger

---
name: "cron-scheduling-stinger"
license: AGPL-3.0-or-later
description: "Design reliable scheduled jobs. Use for cron expressions, DST, distributed execution, retries, idempotency, or monitoring. Read README.md for the guide map."
---

# cron-scheduling-stinger

Procedural arsenal for `cron-scheduling-wasp-drone`, the Wasp Nest's scheduled-job specialist. This stinger encodes everything needed to design, implement, secure, and monitor scheduled jobs across the platforms a Next.js / TypeScript / Node.js team typically uses.

## When this stinger applies

Load this stinger whenever the work involves:

- Authoring or auditing a cron expression (POSIX, Vercel, Cloudflare, GitHub Actions)
- Diagnosing a job that fires twice (distributed duplication) or never (missed run)
- Setting up monitoring so a missed or failed run pages someone within one schedule period
- Designing a scheduled job to survive DST transitions without skipping or doubling
- Building a retry strategy that doesn't make idempotency mistakes
- Reviewing platform limits before choosing where to host a scheduled job

Do NOT load for:

- Background jobs triggered by queue messages without a time component (no Stinger for this yet, handle inline)
- CI/CD pipeline design (that is `devops-wasp-drone`)
- Database schema design for job metadata tables (that is `db-wasp-drone`)

---

## First actions when this stinger is loaded

1. Read `guides/00-cron-expression-syntax.md` for the field reference and platform comparison table.
2. Identify the deployment platform (Vercel, Cloudflare, GitHub Actions, POSIX, pg_cron, BullMQ) and read the relevant section of `guides/01-platform-limits.md`.
3. For distributed deployments (>1 replica or region): read `guides/02-distributed-cron-correctness.md` before prescribing any fix.
4. For timezone-sensitive schedules: read `guides/03-timezone-dst-safety.md`.
5. For observability setup: read `guides/05-observability-monitoring.md`.

---

## Core principles (from Command Brief critical directives)

These are non-negotiable. Each guide in this stinger is structured around them.

- **Never generate a cron expression without explaining it in plain English.** See `guides/00-cron-expression-syntax.md`.
- **Always ask about deployment topology before prescribing a distributed-cron fix.** See `guides/02-distributed-cron-correctness.md`.
- **UTC is the safe default; local timezone must be explicitly justified.** See `guides/03-timezone-dst-safety.md`.
- **Heartbeat monitoring is mandatory for business-critical jobs.** See `guides/05-observability-monitoring.md`.
- **Retry handlers must be idempotent before adding retry logic.** See `guides/04-retry-and-failure-handling.md`.
- **Decouple the trigger from the work for long-running jobs.** If a cron job risks exceeding the platform's execution limit, trigger a queue message and return fast. See `guides/01-platform-limits.md`.

---

## Folder layout

```text
cron-scheduling-stinger/
+- SKILL.md                          (this file)
+- README.md                         (one-page human overview)
+- guides/
|  +- 00-cron-expression-syntax.md   (POSIX / Quartz / Vercel / Cloudflare / GitHub Actions field reference)
|  +- 01-platform-limits.md          (Vercel, Cloudflare, GitHub Actions, pg_cron, BullMQ limits + tradeoffs)
|  +- 02-distributed-cron-correctness.md (leader election, idempotency, exactly-once patterns)
|  +- 03-timezone-dst-safety.md      (UTC discipline, IANA timezone, DST cliff handling)
|  +- 04-retry-and-failure-handling.md (backoff, dead-letter, idempotent handler design)
|  +- 05-observability-monitoring.md (Healthchecks.io, Cronitor, self-hosted heartbeat table)
|  +- 06-audit-and-inventory.md      (enumerate all cron jobs in a codebase, risk matrix)
+- examples/
|  +- vercel-cron-happy-path.md      (vercel.json + idempotent Next.js handler + Healthchecks.io ping)
|  +- distributed-duplicate-prevention.md (Redis SETNX leader lock + automatic expiry)
|  +- github-actions-drift-mitigation.md  (workflow_dispatch fallback + heartbeat step)
+- templates/
|  +- cron-job-spec.md               (structured template for specifying a new scheduled job)
+- reports/
|  +- README.md                      (how audit reports accumulate over time)
+- research/                         (DO NOT MODIFY — owned by scripture-historian)
   +- research-summary.md
   +- research-plan.md
   +- index.md
   +- external/                      (10 source notes from the normal-depth sweep)
```

---

## Quick-reference: cron expression cheat sheet

| Field | POSIX 5-field | Quartz 7-field | Vercel | Cloudflare | GitHub Actions |
|---|---|---|---|---|---|
| Seconds | - | 0-59 | - | - | - |
| Minutes | 0-59 | 0-59 | 0-59 | 0-59 | 0-59 |
| Hours | 0-23 | 0-23 | 0-23 | 0-23 | 0-23 |
| DOM | 1-31 | 1-31 | 1-31 | 1-31 | 1-31 |
| Month | 1-12 | 1-12 | 1-12 | 1-12 | 1-12 |
| DOW | 0-7 | 1-7 | 0-6 | 0-6 | 0-6 (Sun=0) |
| Year | - | optional | - | - | - |
| Timezone | - | named | UTC only | UTC only | UTC + IANA (2026) |

Full syntax details: `guides/00-cron-expression-syntax.md`.

---

## Platform selection decision tree

```
Does the job need sub-hourly scheduling?
  YES → Use Cloudflare Workers free tier (min: 1 min) or pg_cron/BullMQ
  NO  → Continue

Is it a Next.js / Vercel project?
  YES → Use Vercel Cron (vercel.json). Check plan tier (Hobby = daily only).
  NO  → Continue

Is it a GitHub repo CI task (report generation, stale-issue cleanup)?
  YES → Use GitHub Actions schedule: (min: 5 min, UTC-only, expect drift).
  NO  → Use pg_cron (Postgres-native) or BullMQ repeatable (Node.js/Redis)
```

Full platform comparison: `guides/01-platform-limits.md`.

---

## Research trail

The `research/` folder was populated by `scripture-historian` at `normal` depth (2025-11-20 to 2026-05-20). Key findings:

- Vercel updated plan limits in January 2026: 100 cron jobs per project on all plans (was 2 on Hobby). Hobby plan still limited to once-per-day minimum frequency.
- GitHub Actions `schedule:` drift is an active January 2026 incident; delays of 22+ minutes observed. GitHub now supports IANA timezone strings in `schedule:` as of early 2026.
- Cloudflare free tier is the canonical workaround for Vercel Hobby users needing sub-hourly schedules.
- `research/research-summary.md` lists 5 open questions for `stinger-forge`: see that file for details.

---

*Forged from `ai-tools/command-briefs/cron-scheduling-wasp-drone-command-brief.md` and `research/`. Part of The Wasp Nest by [Mario Aldayuz a.k.a @thenotoriousllama](https://github.com/thenotoriousllama).*