cron-discipline v1.0.0

name: cron-discipline description: Hardens scheduled jobs (cron, systemd timers, task queues) against overlapping runs, double-processing, and silent failures. Use when writing, reviewing, or fixing a recurring job: idempotency, overlap locks, timeouts, logging, and dead man's switch alerting. metadata: { "includeInPrompt": true }

Cron Discipline

Purpose

Scheduled jobs fail in three boring ways: they run twice at once and corrupt data, they run twice over time and double-send, and they silently stop running. This skill fixes all three: one instance at a time, re-runs that are safe by construction, and an external alarm that fires on silence.

Workflow

1. Lock single-instance execution. Wrap every job so a new trigger exits immediately when the previous run is still alive. See bin/cron_wrap.sh.
2. Make re-runs safe. Assume the job will run twice (overlap, retry, clock skew). Apply one or more from references/idempotency.md: dedup keys with unique constraints, atomic work-claims, business keys.
3. Bound runtime and failure. timeout every job; set -euo pipefail; absolute paths; log start, end, exit code, and items processed to a file, never to the void.
4. Alert on silence, not just on errors. Add a dead man's switch per references/silence_alerting.md. The job pings an external monitor on start, success, and failure. Silence after the expected period is the alarm, and it survives the host dying.
5. Prove it. Induce each failure once in a safe window: kill the host, let two instances race, break the payload. A check nobody saw fire proves nothing.

Output Contract

A hardened job ships with: a single-instance lock, an idempotency mechanism named in writing (dedup key, atomic claim, or business key), a runtime timeout, a log line per run (name, run id, scheduled vs start vs end, status, items), a heartbeat ping URL registered on an external monitor, and a note of which induced-failure test was run and what happened.

Operating Rules

1. Lock first, logic second. The lock wraps the whole job, not the write at the end.
2. Never claim "exactly-once." Aim for idempotent-at-least-once; duplicates become no-ops.
3. Check-then-insert is not a lock. Use the atomic claim (unique constraint insert, SELECT ... FOR UPDATE SKIP LOCKED).
4. The ping URL is a credential. It lives on the node and in the secret store, never in the repo, PR, or issue tracker.
5. Separate silence alerts from failure alerts on different channels or subjects; one channel carrying both teaches people to ignore it.
6. If runtime approaches the schedule interval, either lengthen the interval, partition the work and lock per partition, or split the job into numbered steps that checkpoint. Do not just hope.