Find the stage where changes wait between push and deploy, fix that stage with numbers, and write down what changed and when to look again.

The objective is X = changes merged and deployed per hour, held inside three budgets and one hard limit:

Irreversible damage (destructive migrations, infrastructure, leaked secrets) stays at zero whatever it costs X.

Symbols used across every file: λ = arrival rate (merges/hour); T = merge-path CI minutes; p = failure rate on the merged tree, flakes included; p_mb = merge-breakage rate given the head was green; B = batch size; D = speculation depth.

Finding the constraint. Pull per-PR timestamps for open, ready, head green, approved, enqueued, merged, main verdict and deployed. Label each stage WAIT or WORK; review and queue time are wait. The constraint is the stage with the most queued minutes per week, and Little's law (WIP = λ × lead time) checks the arithmetic. Exploit it, subordinate the other stages to it, then elevate it, and re-measure after every fix because the constraint moves. Cutting CI duration when CI is not the constraint is a cost lever, not a throughput lever.

Pipeline duration. When the pipeline is the constraint, its wall-clock is the slowest chain of dependent jobs, not their sum. A lever that saves runner minutes off that chain lowers C, not F, and the ledger records it as a cost saving.

Lanes and placement. Every check runs in one lane: author pre-push, PR gate (exact head), merge path (the merged tree, or nothing), post-merge main (coalesced runs; drives auto-revert), pre-deploy (the exact artifact) or nightly (never a merge verdict). Place each check by asking, in order: irreversible if it ships (block before merge, human tier); merge-breakable, meaning its result can change when merged with other PRs (run it on the merged tree; otherwise at the PR head only); deterministic (only these may drive auto-revert); and what it adds to T against what it catches. The classification table and the YAML are in .

The default architecture: no merge queue. PRs merge on evidence for their exact head; main verifies itself after merge in coalesced runs, so each run is a batch; deterministic failures are bisected and reverted by code, and the re-land, conflict and flake repairs go to agents as new tasks; deploys follow the newest verified commit; humans own the high-risk tier, the kill switch and a sampled audit. This is the shape Anthropic runs at 30,000+ merges a day, and it holds at low volume too, where each batch is one commit. Never answer with "require branches up to date" or "require green main before merging": both serialise merges. Flip to a merge queue only when the red budget cannot be met, deploys cannot be limited to verified commits, breakages are mostly nondeterministic, or main cannot be reverted; the flip conditions and the queue math are in , and the GitHub implementation is in with .

references/flow.md

ci-flow.sh

references/measuring.md

merge_group

references/levers.md

references/lanes.md

on:

if:

needs:

concurrency:

references/merge-path.md

references/main-health.md

references/merge-loop.md

main-health.md

bots.md

references/github-build.md

assets/github/

github-build.md

.github/

merge-loop.json

loop.sh

pr

main-verify

merge-loop

agent-task

deploy

superfan

audit-sample

references/bots.md

references/flakes.md

references/deploy.md

references/ledger.md

scripts/ci-flow.sh

--since

--base

--workflow

--environment

--json

scripts/ci-timings.sh

--runs N

--event merge_group

scripts/ci-health.sh

Every script is read-only, takes (or ), and prints its forms with . holds scenarios and the with-versus-without comparison for changing this skill; it never loads during a task.

Copy this checklist to track progress:

CI speedup progress:
- [ ] Step 1: Find the constraint (per-stage WAIT and WORK minutes per week)
- [ ] Step 2: Measure the constraint stage (pipeline, merge path, main, or deploy)
- [ ] Step 3: Decide with numbers (predicted X, R, C; one option; its flip condition)
- [ ] Step 4: Change it on a branch; re-time locally; dry-run every bot
- [ ] Step 5: After-measurement from the branch's own runs or a bot replay
- [ ] Step 6: Ledger, decision record, instruction-file lines, re-measure date

Run against the default branch and name the constraint in a sentence: which stage, WAIT or WORK, minutes per week, and how it compares with the next stage. A scoped ask (one suite, one job) skips to Step 2's pipeline branch. With fewer than about 20 merged PRs in the window, reason from the workflow config and the volumes the user states, and label every number a projection.

State the predicted change in X, R and C, one recommended option, and the measurement that would flip it. When wall-clock falls and runner minutes rise, say by roughly how much and whether the repository pays for minutes.

Edit workflow, test and bot configuration in one branch, and re-time locally whatever can be measured without pushing. A change that makes a shard fail is a finding, not a reason to skip the shard. Dry-run every bot that writes by replaying the red episodes from Step 2 and listing what it would have reverted, repaired or re-queued. Building the merge loop: on GitHub, install by the setup order in , adapt and the setup action to the repository, prove it on a throwaway repository first, ship it at rung 0, and promote only on replay numbers.

Keep the guards. Change detection, concurrency groups, merge checks and deploy gates usually exist because of a past incident; move them, never drop them, and keep the comment that cites the incident next to the guard.

The branch's own runs are the after-measurement; apply the after-run rules in before crediting a lever. When predicted and measured disagree, find out why before adding another lever. A change that waits on a repository setting the user owns gets its after-measurement on the re-measure date, and the ledger says so. Repeat Steps 2 to 5 until the constraint moves to another stage or the remaining options need a decision the user owns.

Write the ledger from into the repository's docs: before, changes, after with run ids, the flow-metric trend row, the decision record with its flip conditions, the queue of options not taken with what each waits on, and the re-measure date. Add the instruction-file lines that stop the layout regressing.

Granted without a check-in, because each is read-only, branch-local or reversible: reads, running the scripts, local re-timing, pushing the working branch, and opening PRs, revert PRs included.

The user's call, because each spends money or changes what every other change must pass:

Done means a mergeable change, after-numbers from real runs or a bot replay, a decision record with its flip conditions, and a ledger row with a re-measure date.