CI/CD Optimize

Diagnose slow CI/CD from evidence, optimize the critical path, close the feedback loop on the exact commit, and prove the pipeline remains effective. Never make a pipeline faster by deleting the checks that make it useful.

When to use — and when not to

Use for: slow median or p95 feedback; long runner queues; repeated setup or dependency restore; cache misses and expensive cache transfers; excessive test time or flakiness; duplicate/stale/irrelevant runs; runner sizing and pool contention; CI cost; watching a pushed commit to a terminal verdict; deployment pipeline convergence and artifact identity.

Not for:

• A one-line YAML syntax or typo fix with no performance question — just fix it.
• Application runtime performance (slow endpoints, page loads) — that is app profiling, not pipeline work.
• Executing a deployment when optimization is not the task — use the deployment workflow/skill for the target platform.
• Reviewing code or hunting product bugs — use the review workflow.
• Any request to delete or bypass required tests or security gates to "go faster" — decline and offer scope/parallelism/cache alternatives.

Analysis is not authorization

Reading configuration and history, computing baselines, drafting recommendations, editing local files on request, and running validators are normal work — proceed. The following change shared or external state and require explicit authorization every time, no matter how confident the analysis is:

• pushing or merging beyond what was asked,
• cancelling or re-running other people's CI runs,
• deleting caches, changing CI/org/repository settings or firewall rules,
• SSH into live runners,
• deployments, promotions, rollbacks, production migrations,
• weakening, skipping, or un-requiring any gate.

Operating loop

Follow the full engagement sequence in references/optimization-workflow.md — read it before touching any workflow YAML. The compressed shape:

1. Frame — exact pipeline, event/branch, current median/p95, failure rate, required gates. Separate queue / setup / execution / transfer / finalization time; they have different fixes.
2. Measure — comparable runs, same commit, median and p95, cache hit/miss, per-job timing and DAG. Protocol in references/measurement.md.
3. Locate the critical path — job DAG from real dependencies. Big CPU-time savings off the critical path buy zero wall-clock. Order of attack: don't start it → cancel stale work → reuse verified work → shorten the path → move fewer bytes → only then add compute.
4. Choose one bounded experiment — smallest reversible change; state evidence, expected wall-clock impact, effectiveness risk, cost, rollback.
5. Verify remotely on the exact SHA — push, then watch to a terminal verdict with references/feedback-loops.md and scripts/ci-watch.py. Compare matched before/after runs; report the evidence rung reached.
6. Stop — when the bottleneck is no longer material, when two repairs fail the same way, or when only gate-weakening ideas remain.

Routing: what is dominant?

1. Duplicate, stale, draft-only, or unrelated work starting? → references/github-actions.md, references/change-based-ci.md.
2. Queue time dominates p95, or jobs multiply past the concurrency ceiling? → references/capacity-and-contention.md, then references/runners-and-autoscaling.md.
3. Setup or dependency restore dominates? → references/typescript-toolchain.md, references/caching.md.
4. Checkout, cache transfer, Docker context, or artifacts dominate? → references/network-and-artifacts.md.
5. Work unrelated to the change runs anyway? → references/change-based-ci.md, references/monorepos.md.
6. Tests dominate or flake? → references/testing-and-flakiness.md, references/integration-environments.md.
7. Docker/OCI builds dominate? → references/containers.md.
8. Security scans dominate? → references/security-gates.md.
9. Deployment is slow, repeated, or unverifiable? → references/deployment.md.
10. Swift/Xcode pipeline? → references/swift-xcode.md.
11. Provider mechanics themselves? → references/github-actions.md, references/gitlab-ci.md, references/circleci.md, references/buildkite.md.
12. Build-graph correctness or remote execution? → references/bazel-and-remote-execution.md.
13. Waiting on a pushed commit, reacting to red, or wiring a watcher? → references/feedback-loops.md; run scripts/ci-watch.py (do not read its source — --help documents the contract).
14. About to weaken validation, trust boundaries, or artifact identity? → references/effectiveness-contract.md first.
15. Load-bearing vendor claim unverified or stale? → references/evidence-and-sources.md.

Common pitfalls

Reference files

Optional: Avrea reference kit

Read only when the repository runs on Avrea (runs-on: labels start with avrea-) or Avrea is being evaluated as a runner change. The core loop is provider-neutral. Probe first: command -v avr && avr --version && avr auth status.

Guardrails

• Verify mutable vendor behavior against current official docs when it is load-bearing; record the check per references/evidence-and-sources.md. Version-sensitive pins in examples carry a verify-current note.
• Probe before depending on any platform CLI (command -v, --version, auth status); fall back to provider-native evidence when absent.
• Treat every mutating platform command as an authorization gate (see "Analysis is not authorization" above). Confirmation prompts and --yes flags are mechanics, not permission.
• A green check is evidence only for its exact head_sha and artifact digest. Stale-SHA greens, wrong-branch greens, and retried-into-green flakes are not proof.
• Full validation is the fallback whenever changed files, merge base, cache correctness, graph completeness, or security scope cannot be proven.
• Do not add heavy machinery (Bazel, remote execution, self-hosted fleets, commercial test selection) unless the measured bottleneck and operating capacity justify it.

Report contract

Complete work reports, in order: baseline (window, sample size, median/p95, queue vs execution split); the chosen bottleneck with critical-path evidence; the exact change (files/config); before/after comparison on matched runs with exact run IDs and head_sha; effectiveness checks (gates, cache trust, artifact identity); cost effect; remaining risks and rollback; the evidence rung actually reached (config review → syntax check → one run → repeated runs → production); disproved or neutral hypotheses; and any provider branch not exercised. Missing evidence is stated, never implied away.