/cloud-checkup

name: cloud-checkup
description: >-
  Read-only SRE checkup of any GCP project: deterministic probes of the edge, Cloud Run
  services, 7-day error logs, Cloud Scheduler, alert policies and uptime checks, Secret
  Manager and IAM, the data stores and the machine's own scheduled jobs, audited into one
  fixed status table (LIVE / WARNING / RED / INCONCLUSIVE) with evidence, findings by
  severity, what could not be checked, and a single OVERALL line delivered as one
  notification. Parametrised by a per-project manifest, so the same routine runs on every
  project. Use when the operator says "cloud checkup", "SRE check", "is everything live",
  "what's healthy / warning / red", "any errors this week", "audit the infra", "weekly
  checkup", "set up the weekly checkup", before a deploy or demo, or after an incident.
  Cloud Run first; App Engine and GKE differ only in the
  serving probes.
argument-hint: "[--manifest <path>] [--probes-only] [--install-schedule]"

cloud-checkup

One routine, two entry points: in-session (you are the inspection layer) and headless (scheduled or on demand). Both fill the same template, so two runs are comparable.

Read-only throughout. It never deploys, never mutates cloud state, never restarts or unpauses anything.

Three layers

| Layer | What it does | Survives without the next layer | |---|---|---| | 1. Deterministic probes | `scripts/cloud_checkup.sh`: curl, `gcloud ... describe`, `gcloud logging read`, scheduler, monitoring, secrets, IAM, local jobs. Writes a probes file. | Yes. The probes file is the artefact of record. | | 2. Read-only inspection | Headless `claude -p` (or you, in session) reads the probes, queries the data stores, fills `templates/CHECKUP-TEMPLATE.md` into the report. | Yes. Without it the report is the probes file plus `OVERALL: INCONCLUSIVE`. | | 3. One notification line | `scripts/notify.sh` posts the `OVERALL` verdict and the report path. | Yes. Suppressed with `CC_NO_NOTIFY=1`. |

Layer 1 exists so the routine still has value when the model is unavailable, rate-limited or wrong. Never let layer 2 be the only thing that ran.

Status legend

| Status | Rule | |---|---| | 🟢 LIVE | The check passes and that feature had zero errors in the review window. | | 🟡 WARNING | It serves, but had errors in the window, or is degraded, paused, stale beyond its threshold, or drifted from the source of truth. | | 🔴 RED | It errors right now, is down, or is halted. | | ⚪ INCONCLUSIVE | It could not be read from this seat. Say what would be needed. |

**`PERMISSION_DENIED` reads as INCONCLUSIVE, never as zero.** A denied `logging read` returns no rows; scoring that as "no errors" turns a blind seat into a green light. Every probe captures stderr and marks the row INCONCLUSIVE on any permission or API error. INCONCLUSIVE is a capability gap of the seat, not a health signal.

Identity discipline

The machine's default `gcloud` account drifts between identities, and a stored credential can mint a token for a different principal than the one you asked for.

1. **Pin `--account` on every call.** The script wraps `gcloud` in a `gc()` helper that always passes it. Never `gcloud config set account`: it mutates state the operator's other work depends on, and it survives the run. 2. **Verify the token identity, not the config.** The script mints an access token for the pinned account and reads the `email` back from `https://oauth2.googleapis.com/tokeninfo`. If that email is not the pinned account, the whole cloud plane is INCONCLUSIVE regardless of what the probes returned, because the reads were made as somebody else. The token goes over stdin, never into argv, and never into the probes file. 3. **Record the observed default** alongside the pinned account, so drift is visible without being acted on.

Manifest

Everything project-specific lives in one YAML file. Copy `manifest.example.yaml` to the project (`.cloud-checkup.yaml` at the repo root is the convention) and fill it in: project, region, account, services, public URL and edge routes, expected security headers, log review window, data stores, local jobs, ticket map, extra rows, notification sink, schedule. The probe script reads it with `yq` when present, PyYAML next, and a small built-in parser last; the inspection layer reads the file itself, so richer structures (data stores, ticket map, extra rows) need no parser support.

Run it

CC=~/.claude/skills/cloud-checkup

# In session: probes only, then you fill the template as layer 2.
CC_SKIP_AI=1 CC_NO_NOTIFY=1 CC_MANIFEST=.cloud-checkup.yaml "$CC/scripts/cloud_checkup.sh"

# Headless, full run (probes + inspection + notification).
CC_MANIFEST=.cloud-checkup.yaml "$CC/scripts/cloud_checkup.sh"

In-session, after the probes land: read the probes file, query each data store in `data_stores[]` (see `modules/` for the per-type routine), fill every row of `templates/CHECKUP-TEMPLATE.md`, compare against the previous report in the report directory for "Changed since", map findings to `ticket_map`, and end the file with exactly one `OVERALL:` line. Point `CC_OUT` at a scratch path when running probes-only, so the stub never lands on the canonical report name. Lead the chat reply with RED rows, then WARNING, then the `OVERALL` line and the report path. Do not commit; the operator does.

Schedule it

Weekly is the right cadence: often enough to catch a dead writer before its data expires, rare enough that the report is read.

• **macOS:** fill `templates/launchd.plist.tmpl`, install to `~/Library/LaunchAgents/`,

`launchctl load` it. `StartCalendarInterval` uses local time, so the hour tracks the operator's clock through DST with no UTC conversion.

• **Linux and elsewhere:** `templates/cron.example`, or a systemd timer of the same shape.

**Logs never go in `/tmp`.** macOS purges `/tmp` after three days of no access, and it does it while a long-lived process still holds the descriptors, so th