Cron Schedule Planner

---
name: cron-schedule-planner
description: "Builds an overview of GitHub Actions `schedule` cron expressions across multiple repositories and helps spread CPU-intensive jobs (Docker Compose, Testcontainers, Kind/k3s, matrix builds) into less contended slots. Use when the user asks 'when do my cron actions run?', 'do my scheduled builds collide?', 'when should the Testcontainers build run?', or wants a cron schedule overview/distribution report across repos. Scans via `gh` (no local checkouts required) or local checkouts, converts UTC to a local timezone, classifies job intensity, and writes a Markdown report with an hourly histogram, collisions and concrete cron redistribution suggestions."
---

# Cron Schedule Planner

Collects GitHub Actions `on.schedule` cron expressions across repositories,
classifies how resource-intensive each workflow is, converts the UTC cron times
to a local timezone, and produces a Markdown report with an hourly histogram,
collisions and concrete redistribution suggestions.

Read-only: the script never edits workflows. Suggestions are applied only after
the user confirms.

## Instructions

### Step 1: Decide the repository scope

- Default: all repositories of the authenticated `gh` user (no local checkouts
  needed).
- `--owner <owner>` to scan a different owner.
- `--repo <owner/repo>` (repeatable) for an explicit list.
- `--local <dir>` to scan local checkouts instead of the GitHub API.

### Step 2: Run the script

```bash
bash scripts/cron-schedule-planner.sh
```

Common variants:

```bash
# Specific owner, Swiss local time, report in target/
bash scripts/cron-schedule-planner.sh --owner dboeckli --tz Europe/Zurich

# Local checkouts (no GitHub API)
bash scripts/cron-schedule-planner.sh --local ~/projects/referenzen

# A few explicit repos
bash scripts/cron-schedule-planner.sh --repo dboeckli/ai-agent-skills --repo dboeckli/camel-first
```

### Step 3: Present the results

The script prints the hourly histogram, collisions and suggestions, and writes
`target/cron-schedule-overview.md`. Summarise:

- how many repos / scheduled entries were found,
- the most crowded UTC hours (collisions),
- which high-intensity jobs sit in crowded hours.

### Step 4: Apply suggestions only after confirmation

The redistribution suggestions are heuristic (they move high-intensity jobs out
of crowded hours into empty ones, keeping the minute and day fields). Present
them as a diff and change workflow files **only after explicit confirmation**.
Never edit automatically.

## Options

| Option                | Meaning                                                         |
| --------------------- | --------------------------------------------------------------- |
| `--owner <owner>`     | GitHub owner to scan (default: authenticated user)              |
| `--repo <owner/repo>` | explicit repo (repeatable); disables owner scan                 |
| `--local <dir>`       | scan local checkouts under `<dir>` instead of GitHub            |
| `--tz <zone>`         | local timezone for the `Local` column (default `Europe/Zurich`) |
| `--limit <n>`         | max repos for the owner scan (default 200)                      |
| `--out <file>`        | Markdown report (default `target/cron-schedule-overview.md`)    |
| `--no-report`         | console only, no report file                                    |
| `--top <n>`           | max redistribution suggestions (default 5)                      |
| `--queue-stats`       | add observed queue time per UTC hour (via `gh run list`)        |
| `--runs <n>`          | max runs per repo for queue stats (default 50)                  |

## Output

`target/cron-schedule-overview.md`:

- **Scheduled workflows** table: repo, workflow, cron (UTC), UTC time, local
  time, frequency, intensity, evidence.
- **Runs per UTC hour** histogram (bars).
- **Runs per frequency / weekday**.
- **Collisions** — UTC hours with two or more scheduled runs.
- **Observed queue time per UTC hour** (with `--queue-stats`) — average and max
  wait between `createdAt` and `startedAt` across recent runs, as an empirical
  contention signal.
- **Redistribution suggestions** — high-intensity jobs in crowded hours moved
  to empty ones; with `--queue-stats` the empty hours with the lowest observed
  queue are preferred.

## Classification

Intensity is derived heuristically from the workflow content. See
`references/classification-and-timezones.md` for the exact patterns and the
UTC/timezone rules.

- **high** — Docker Compose, Testcontainers, service containers (`services:`),
  Kind/k3s cluster, matrix builds.
- **medium** — Maven/Gradle full builds, Docker image builds.
- **low** — lint/format/validate and other meta workflows.

## Examples

### Example 1: Are my scheduled builds colliding?

User says: "Do my scheduled GitHub Actions builds collide?"

Actions:

1. Run `bash scripts/cron-schedule-planner.sh --owner <owner>`
2. Report the crowded UTC hours and the high-intensity jobs in them
3. Point to `target/cron-schedule-overview.md`

Result: Collision overview across all repos with concrete evidence.

### Example 2: When should the Testcontainers build run?

User says: "When should I schedule the Testcontainers build?"

Actions:

1. Run the planner and locate the crowded hours (collisions)
2. Recommend one of the empty hours from the suggestions
3. Offer the concrete cron diff, apply only after confirmation

Result: A low-contention slot and a ready-to-apply cron change.

## Troubleshooting

### `gh: not found` or authentication error

The script needs an authenticated `gh`. Run `gh auth status`; if that fails, the
user must authenticate. Alternatively use `--local <dir>` with local checkouts.

### Empty report

No workflow in scope has an `on.schedule` entry. Check the repo scope
(`--owner`, `--repo`, `--local`) and that the workflows actually define
`schedule:` crons.

### Times look off by one hour

Cron is always UTC. Local times are computed for the current date, so
daylight-saving transitions can shift them by one hour. Re-run after a DST
change or adjust manually.

### `--queue-stats` shows little or no data

GitHub reports `startedAt` equal to `createdAt` for most runs (no recorded
queue), so the signal is sparse. Increase `--runs` to include older runs.
Treat large gaps with care: they can come from approval gates, concurrency
limits or manual runs, not only runner contention.