feat: add cron-doctor — diagnose cron death-traps before they ship (#757)

Author: takeaseatventure

README.md

@@ -349,6 +349,7 @@ Key source families include:
 
 - **[mattpocock/skills](https://github.com/mattpocock/skills)**: Source for 17 Matt Pocock workflow skills - codebase design, TDD, bug diagnosis, triage, PRDs, issues, prototyping, handoff, teaching, and skill-writing guidance (MIT).
 - **[emilkowalski/skills](https://github.com/emilkowalski/skills)**: Source for Emil Kowalski design engineering skills - UI polish, motion review, animation standards, component craft, and high-taste frontend guidance (MIT).
+- **[takeaseatventure/devops-skills](https://github.com/takeaseatventure/devops-skills)**: Source for the `cron-doctor` skill - cron expression diagnosis, validation, trap detection, and zero-dependency schedule analysis tooling (MIT).
 - **[drogers0/gh-image](https://github.com/drogers0/gh-image)**: Source for the `gh-image` skill - GitHub CLI image uploads that return canonical `user-attachments` embed URLs for PRs, issues, comments, and README screenshots (MIT).
 - **[Genefold/arrowspace-skills](https://github.com/Genefold/arrowspace-skills)**: Source for the `arrowspace` skill - spectral vector search using graph Laplacian eigenstructure for structurally aware retrieval (Apache-2.0).
 - **[yaojingang/yao-meta-skill](https://github.com/yaojingang/yao-meta-skill)**: Source for the `yao-meta-skill` skill - governed skill creation, refactoring, evaluation, packaging, review, and distribution workflows (MIT).

skills/cron-doctor/SKILL.md

@@ -0,0 +1,244 @@
+---
+name: cron-doctor
+description: "Diagnose and validate cron expressions before they ship. Catches the five silent death-traps: impossible dates that never fire, OR-semantics that fire too often, midnight spikes, uneven step drift, and leap-year February 29."
+category: devops
+risk: safe
+source: community
+source_repo: takeaseatventure/devops-skills
+source_type: community
+date_added: "2026-06-26"
+author: takeaseat
+tags: [cron, crontab, scheduling, devops, debugging, kubernetes, validation]
+tools: [claude, cursor, codex, gemini, opencode]
+license: "MIT"
+license_source: "https://github.com/takeaseatventure/devops-skills/blob/main/LICENSE"
+---
+
+# cron-doctor
+
+## Overview
+
+Cron is deceptively error-prone. The failure mode is **silent** — a syntactically
+valid expression that simply never fires, or fires far more often than intended.
+`0 0 30 2 *` parses cleanly and then sits dead forever (February has no 30th).
+`0 0 1,15 * 1` looks like "1st and 15th if Monday" but actually means "1st, 15th,
+**OR** every Monday" — ~6 fires/month instead of ~2.
+
+This skill teaches an agent to catch those before they reach production. It comes
+with a zero-dependency validation engine (`scripts/cron-engine.js`, no install
+needed) that parses, describes, deep-validates, and computes next fire times.
+
+## When to Use This Skill
+
+- Use when a user writes, edits, reviews, or deploys a cron expression — in a
+  crontab, a Kubernetes `CronJob`, a GitHub Actions `schedule`, an Airflow DAG,
+  a Celery beat schedule, a systemd timer, or any scheduled task.
+- Use when debugging a job that "didn't fire" or "fired at the wrong time."
+- Use when a user asks "what does this cron expression mean?" or "when will this
+  run next?" or "how often does this run per year?"
+- Use when reviewing a CI/CD pipeline or infrastructure config that contains a
+  `schedule` field.
+- Use when a user pastes a 5-field cron expression and asks for a sanity check.
+
+## How It Works
+
+### Step 1: Parse the expression
+
+Split on whitespace into 5 fields: minute, hour, day-of-month, month, day-of-week.
+Confirm valid ranges:
+
+| Field | Position | Range | Notes |
+|-------|----------|-------|-------|
+| minute | 1 | 0–59 | |
+| hour | 2 | 0–23 | |
+| day-of-month | 3 | 1–31 | |
+| month | 4 | 1–12 | names (JAN–DEC) accepted |
+| day-of-week | 5 | 0–7 | 0 and 7 both = Sunday; names (SUN–SAT) accepted |
+
+### Step 2: Describe it in plain English
+
+State what the user *thinks* it does vs. what it *actually* does. Be explicit
+about OR-vs-AND semantics for day-of-month + day-of-week (see death-trap #2).
+
+### Step 3: Run the trap checklist
+
+Check the five death-traps below and flag any that apply.
+
+### Step 4: Calculate next runs and annual fire count
+
+Compute the next 5 fire times as concrete dates so the user can verify the
+schedule behaves as expected. Estimate annual fire count — a schedule that fires
+365×/year vs. 12×/year is a ~30× cost and load difference.
+
+## The Five Cron Death-Traps
+
+These are the bugs that pass `crontab -l` validation but break in production.
+
+### 1. Impossible dates — the "never fires" bug
+
+```
+0 0 30 2 *
+```
+
+**Valid syntax. Never fires.** February has no 30th. This schedule is a dead job
+that silently sits forever. The same applies to day 31 in any 30-day month:
+`0 0 31 4 *`, `0 0 31 6 *`, `0 0 31 9 *`, `0 0 31 11 *`.
+
+**Fix:** use `0 0 28-31 * *` and check for end-of-month in the script, or use `L`
+(last day) syntax if your scheduler supports it.
+
+### 2. OR-semantics — the "fires too often" bug
+
+```
+0 0 1,15 * 1
+```
+
+**Does NOT mean** "midnight on the 1st and 15th if it's Monday."
+**Does mean** "midnight on the 1st, the 15th, **OR** every Monday." That's ~6
+fires/month instead of ~2.
+
+This is the single most misunderstood cron rule. When **both** day-of-month AND
+day-of-week are restricted (neither is `*`), cron uses OR logic, not AND.
+
+**Fix:** if you need "1st and 15th only if Monday," run daily and check in the
+script:
+
+```bash
+0 0 * * 1 [ "$(date +%d)" = "01" -o "$(date +%d)" = "15" ] && your-command
+```
+
+### 3. Midnight spike — the "everything at once" bug
+
+```
+0 0 * * *
+```
+
+Every job scheduled at `0 0` competes for resources at exactly 00:00. Database
+backups, log rotations, cert renewals, report generation — all fire simultaneously.
+This causes load spikes, connection-pool exhaustion, and cascading timeouts.
+
+**Fix:** stagger jobs across the hour. Use `17 2 * * *` or `43 3 * * *` instead of
+`0 0`. Jitter is your friend.
+
+### 4. Uneven steps — the "drift" bug
+
+```
+*/7 * * * *
+```
+
+**Does NOT mean** "every 7 minutes evenly." It means "every 7 minutes starting at
+0, then resets at 60." So: 0, 7, 14, 21, 28, 35, 42, 49, 56 — then 0 again
+(a 4-minute gap). The intervals drift: 7,7,7,7,7,7,7,7,**4**.
+
+**Fix:** 60 is not divisible by 7. Use step values that divide 60 evenly: `*/5`,
+`*/10`, `*/15`, `*/20`, `*/30`. If you truly need every-7-minutes, use a loop with
+`sleep 420`.
+
+### 5. Leap-year February 29 — the "annual surprise"
+
+```
+0 0 29 2 *
+```
+
+Fires only on leap years — February 29, 2024 / 2028 / 2032… If someone writes this
+expecting "end of February," they'll be confused for 3 out of every 4 years.
+
+**Fix:** use `0 0 28 2 *` and handle the 29th case in the script if needed.
+
+## Using the validation script
+
+This skill ships a zero-dependency engine at `scripts/cron-engine.js` (Node.js, no
+`npm install` needed). You can use it programmatically or from the CLI:
+
+```javascript
+// Programmatic — Node.js, zero dependencies
+const { describe, validate, nextRuns, formatNextRuns } = require('./scripts/cron-engine.js');
+
+// Parse + describe -> returns { text, error, parsed }
+const d = describe('0 0 30 2 *');
+console.log(d.text);   // "At 00:00, on day-of-month 30 in in FEB"
+
+// Deep validation -> catches the traps
+const result = validate('0 0 30 2 *');
+console.log(result.valid);              // true (syntax is valid)
+console.log(result.observations);       // includes the "never fires" insight
+console.log(result.suggestions);        // e.g. "Midnight is a common spike..."
+
+// Next 5 fire times -> returns Date[]
+const runs = nextRuns('0 9 * * 1-5', new Date(), 5);
+console.log(formatNextRuns(runs, new Date())); // [{ date, relative, formatted }, ...]
+```
+
+```bash
+# CLI (via the bundled wrapper)
+node scripts/cli.js describe "*/5 * * * *"
+node scripts/cli.js validate "0 0 30 2 *"
+node scripts/cli.js next "0 9 * * 1-5" 5
+```
+
+## Common cron presets
+
+| Expression | Description | Use case |
+|-----------|-------------|----------|
+| `*/5 * * * *` | Every 5 minutes | Health checks, polling |
+| `0 * * * *` | Every hour | Hourly aggregation |
+| `0 */2 * * *` | Every 2 hours | Semi-frequent sync |
+| `0 9 * * 1-5` | 9am Mon–Fri | Business-hours task |
+| `0 2 * * *` | 2am daily | Off-peak batch (avoid midnight) |
+| `0 0 * * 0` | Midnight Sunday | Weekly maintenance |
+| `0 0 1 * *` | Midnight 1st of month | Monthly report |
+| `0 0 1 1 *` | Midnight Jan 1st | Annual task |
+
+## Best Practices
+
+- ✅ Always provide the plain-English description AND run the trap checklist.
+- ✅ Stagger midnight jobs to avoid the spike.
+- ✅ Prefer step values that divide 60 evenly (`*/5`, `*/15`, `*/30`).
+- ✅ Add a comment above every crontab line explaining intent.
+- ✅ Set an explicit timezone (`CRON_TZ`) on schedulers that support it.
+- ❌ Don't trust `crontab -l` validation — it only checks syntax, not semantics.
+- ❌ Don't restrict both day-of-month and day-of-week without confirming OR-logic.
+- ❌ Don't schedule everything at `0 0`.
+
+## Common Pitfalls
+
+- **Problem:** "My cron job isn't running."
+  **Solution:** Check for an impossible date (trap #1) and confirm the daemon is
+  running (`service cron status` / `systemctl status crond`). Verify the file
+  ends with a newline and has correct ownership.
+
+- **Problem:** "My job runs far more often than expected."
+  **Solution:** You hit OR-semantics (trap #2). If both day-of-month and
+  day-of-week are set, cron ORs them. Move one to `*` or guard in-script.
+
+- **Problem:** "Intervals are uneven — sometimes 7 min, sometimes 4."
+  **Solution:** Step value doesn't divide 60 evenly (trap #4). Use a divisor of 60.
+
+- **Problem:** "My job works locally but not in the cluster."
+  **Solution:** Timezone mismatch. Kubernetes `CronJob` and GitHub Actions default
+  to UTC. Confirm `timeZone` / `TZ` is set as intended.
+
+## Limitations
+
+- This skill targets standard 5-field cron as implemented by Vixie cron, systemd
+  timers, Kubernetes `CronJob`, GitHub Actions `schedule`, and most libraries. It
+  does **not** validate Quartz 6/7-field expressions with seconds/years, nor
+  non-standard `@reboot` / `L` / `#` extensions without a note.
+- Estimated annual fire counts assume a non-leap reference year; February 29
+  schedules (trap #5) are flagged explicitly.
+- This skill does not replace environment-specific validation, testing, or expert
+  review. Stop and ask for clarification if required inputs, permissions, or
+  safety boundaries are missing.
+
+## Related Skills
+
+- `docker-expert` — when the cron job runs inside a container and the issue is the
+  container/entrypoint rather than the schedule.
+- `kubernetes-deployment` — when validating a `CronJob` manifest's `spec.schedule`
+  field alongside the broader resource config.
+
+## Security & Safety Notes
+
+This skill is read-only and `risk: safe`. The validation script performs no file
+writes, network calls, or mutations — it only parses and computes. It is safe to
+run against any cron expression without preconditions.

skills/cron-doctor/scripts/cli.js

@@ -0,0 +1,75 @@
+#!/usr/bin/env node
+'use strict';
+
+// Minimal CLI wrapper for cron-engine.js. Zero dependencies.
+// Usage:
+//   node cli.js describe "<cron>"
+//   node cli.js validate "<cron>"
+//   node cli.js next "<cron>" [count]
+
+const cron = require('./cron-engine.js');
+const expr = process.argv[3];
+const cmd = process.argv[2];
+
+if (!cmd || !expr) {
+  console.error('Usage: node cli.js <describe|validate|next> "<cron-expr>" [count]');
+  console.error('Examples:');
+  console.error('  node cli.js describe "*/5 * * * *"');
+  console.error('  node cli.js validate "0 0 30 2 *"');
+  console.error('  node cli.js next "0 9 * * 1-5" 5');
+  process.exit(2);
+}
+
+function safe(fn) {
+  try {
+    fn();
+  } catch (e) {
+    console.error('Error: ' + (e.message || e));
+    process.exit(1);
+  }
+}
+
+switch (cmd) {
+  case 'describe':
+    safe(() => {
+      const d = cron.describe(expr);
+      console.log(d.text || d.description || JSON.stringify(d));
+    });
+    break;
+
+  case 'validate':
+    safe(() => {
+      const r = cron.validate(expr);
+      console.log('valid: ' + r.valid);
+      if (r.description) console.log('description: ' + r.description);
+      if (r.warnings && r.warnings.length) {
+        console.log('warnings:');
+        r.warnings.forEach((w) => console.log('  - ' + w));
+      }
+      if (r.observations && r.observations.length) {
+        console.log('observations:');
+        r.observations.forEach((o) => console.log('  [' + (o.level || 'info') + '] ' + o.message));
+      }
+      if (r.suggestions && r.suggestions.length) {
+        console.log('suggestions:');
+        r.suggestions.forEach((s) => console.log('  [' + (s.level || 'info') + '] ' + s.message));
+      }
+    });
+    break;
+
+  case 'next':
+    safe(() => {
+      const count = parseInt(process.argv[4] || '5', 10);
+      const runs = cron.nextRuns(expr, new Date(), count);
+      const formatted = cron.formatNextRuns(runs, new Date());
+      formatted.forEach((f) =>
+        console.log(f.relative + '\t' + f.formatted + '\t' + f.date.toString())
+      );
+    });
+    break;
+
+  default:
+    console.error('Unknown command: ' + cmd);
+    console.error('Commands: describe, validate, next');
+    process.exit(2);
+}