instructa/agent-skills/lean-ci

Lean CI

Most CI advice is generic: cache everything, add path filters, cancel stale runs, split into matrices, run nightly, select tests smartly. Each item sounds cheap, but each one is another thing to maintain and another way to silently skip a check. Right-sizing CI means finding the one or two changes that remove most of the measured cost and dropping the rest.

The question that drives everything: what must CI prove that a developer or agent cannot prove locally? That part stays. Everything else should be as fast and as few as possible, and most of it belongs before the push.

1. Measure before proposing

Do not suggest a single change before you have looked at the real data. Collect:

• Workflows and triggers: which files run on which events (push, pull_request,

schedule, workflow_dispatch), with or without filters and concurrency.

• Run history: e.g. gh run list --limit 100 --json event,headBranch,status,conclusion,createdAt,updatedAt,headSha.

Count runs per day, per event and per branch. Does the team actually use PRs, or does everything go straight to one branch?

• Where the time goes: step durations from a recent green run (gh run view <id> --json jobs).

Usually two or three steps account for most of the minutes.

• Why runs fail: read the failing step of each red run. Group failures by cause, and note

timing. Failures clustered on one day that then stop point to a real, fixed break, not flakiness.

• What reaches CI that should have been caught locally: fast checks (typecheck, boundary or

lint scripts) that failed in CI are the strongest argument for a local gate.

• Cost context: private repos burn paid minutes; public repos mostly cost wait time.
• What CI already covers: compare the tested files against the full suite. Often CI already

runs a subset and the "stop running everything" advice is already satisfied.

• What depends on CI output: docs, release notes or plans that cite a run for an exact

commit, image digests, architecture-specific proof (x64 vs. local ARM), hermetic or network-less runs. These are evidence and must keep producing the same proof.

Also read AGENTS.md, CLAUDE.md, contributing docs and existing hooks, so you know what the project promises and what it already enforces.

2. Separate "what it proves" from "when it runs"

Classify every expensive step:

• Only CI can prove it (clean environment, target architecture, release artifact, image

hardening): keep it unchanged. Move when it runs, never what it checks.

• A developer can prove it locally in seconds or minutes: move it into a local gate and

keep at most a thin copy in the fast CI job.

• Nobody relies on it: diagnostic wrappers from an old investigation, duplicated builds,

checks whose results are never read. Remove it.

The biggest lever is almost always the same: stop running the expensive proof on every push, and run it where it is actually needed, such as on the release branch, on PRs into it, or manually for a release candidate.

3. Challenge every proposal, including your own

List each candidate change and give it a verdict tied to the numbers from step 1. A change survives only if it removes a measured cost that is larger than the maintenance and risk it adds. Keep the list honest: it is normal for most ideas to be dropped.

Common over-engineering and when it does not pay off:

This table is a starting point, not a verdict. If the data shows a case where the mechanism does pay off, keep it and say why.

4. Keep the local gate minimal and enforced

Written instructions do not enforce anything; a hook does. When fast checks escaped to CI:

• Add one script (e.g. verify) with only the checks that are fast (roughly under a minute) and

have actually failed in CI or protect a core promise of the project.

• Call it from a pre-push hook, committed in the repo (e.g. .githooks/), and activate it

automatically through the package manager's install/prepare step or equivalent.

• Make sure the script produces any generated files it needs, so it does not fail on stale local

state.

• Do not add slow suites to the hook. People and agents bypass slow hooks.

5. Recommend, then implement only what survived

Present the result before editing anything:

1. The three or four facts that shaped the decision (time split, run counts, failure causes,

evidence dependencies).

1. A verdict table: each proposal with keep or drop and a one-line reason from the data.
2. The remaining changes, usually one or two.
3. The explicit trade-off, e.g. "PDF or packaging failures on develop now surface on the next

manual run or on merge, not right after each push."

When implementing:

• Move expensive steps without changing them, so the evidence stays identical.
• Keep the fast job fast; state its expected duration.
• Document the new rules where agents and people read them (AGENTS.md, CLAUDE.md or the

contributing guide): which checks run locally, that hooks are not skipped with --no-verify, how to trigger the expensive proof manually (e.g. gh workflow run <file> --ref <branch>), and to confirm the run tested the intended commit.

• Validate what you can locally: run the verify script, run the hook, parse the workflow YAML.

Say clearly that the new workflow has not run on the CI provider until it is pushed.

• Do not commit, push or trigger workflows without the user's go-ahead.