| name | ci-doctor |
| description | Diagnose CI health and, when needed, benchmark a config change side by side — without re-deriving either from scratch each time. Use when the operator asks "why is CI slow", "diagnose our CI", "is our CI healthy", "what's the bottleneck", or wants to compare wall-clock across two or more `runs-on` (or other config) variants — e.g. GitHub-hosted vs. a paid runner vendor, or a small vs. large runner tier. Not for writing new workflows from scratch, not for non-GitHub-Actions CI systems, not for security/posture audits (a separate free skill, `ci-secure`, from the same catalog, covers that). |
ci-doctor — reusable CI diagnosis + benchmark harness
Born from GH-161: diagnosing and benchmarking this repo's CI was ad-hoc every
time — the same dispatch/poll/watch/tabulate loop hand-written three separate
times in one session, and one silent trap (a push-triggered run classified
into a "fast lane" that skips the real test suite, reporting a meaningless
wall-clock number) that nothing prevented from recurring.
What this is NOT
Diagnosis is a solved problem — don't rebuild it. StarSling's free,
open-source ci-speedup skill already measures the real wall-clock critical
path from run history and identifies the dominant bottleneck step, with an
internal adversarial-verification gate. Verified against this repo in GH-152:
its finding (a specific test step eating ~89% of a job's wall time) matched
independent manual measurement exactly. ci-doctor leans on it rather than
duplicating that engineering.
Step 1 — always diagnose first
npx skills use "https://github.com/starslingdev/skills" --skill "ci-speedup"
Follow the generated instructions verbatim (they are self-contained — repo
target confirmation, the gh-auth gate, the scan, and a plain-English close).
This answers "why is CI slow" for the common case: a single repo's existing
run history, no new runs needed.
Step 2 — only if a side-by-side comparison is needed
ci-speedup analyzes existing history — it does not orchestrate new
comparison runs across config variants. That's the one real gap this skill
fills, with benchmark-runners.sh:
skills/ci-doctor/benchmark-runners.sh \
--repo OWNER/REPO --workflow .github/workflows/ci.yml --base development \
--find 'runs-on: ubuntu-latest' \
--variant 'github-hosted=runs-on: ubuntu-latest' \
--variant 'bigger-runner=runs-on: ubuntu-latest-8-cores' \
--job 'the job display name shown in the Actions UI'
Run from inside a local clone of the target repo (plain git — branch, patch,
commit, push, dispatch; no API workarounds needed, unlike a read-only
diagnostic session that must avoid touching someone else's checkout).
Always forces workflow_dispatch, never a push/PR event — this is the
fix for the fast-lane trap above. Prints a wall-clock + conclusion table
across every named variant. Branches are deleted after each run unless
--keep-branches is passed; nothing is ever merged automatically.
Optional: a paid runner vendor is one more --variant, never a dependency
This skill has zero vendor-specific code. --variant takes any
runs-on value verbatim — a bigger GitHub-hosted runner, a self-hosted
label, or (as one option among many, and the one this project was born
testing — see GH-152) a managed vendor like StarSling, whose sized tiers
(starsling-ubuntu-24.04-2/-8/-16/..., see docs.starsling.dev) are just
another string to pass in. Nothing here requires an account with, a
GitHub App install for, or knowledge of any specific vendor. GitHub-hosted
runners alone are a fully supported, first-class case — comparing against a
vendor is opt-in, not the point of the tool.
What this does NOT do
- Does not pick a winner or auto-adopt a variant — it reports, the operator
decides.
- Does not touch branch protection, required checks, or the target
workflow's default
runs-on — every change lives on a disposable
benchmark branch.
- Does not replace
ci-secure (security posture) or a real load-bearing
CI/CD review — it answers "how slow, and why", nothing else.
