landing-plan

Landing plan

Landing is part of how fast work ships, and it is usually the slowest part nobody measures. Merging one PR at a time with a full CI cycle per PR pays for every flake serially. Most PRs in a set don't depend on each other. Check them all in parallel, batch the independent ones through the merge queue, and keep strict ordering only for PRs that actually depend on each other. At L2 the hand-off has to include the merge plan, not just a list of PRs.

When to use / not use

Use it:

• when a stack or set of PRs (usually 3 or more) is ready for its owners or for gated self-merge;
• when experiment-arms has a composed stack of winners;
• when someone is about to merge a set of PRs serially.

Don't use it:

• for a single PR. Use pr-shepherd.
• for PRs that aren't green on their exact head yet. Finish those first.
• to merge anything above the level granted in docs/autonomy.md. This skill plans at any level and acts only at the level it has been granted.

Steps

1. Inventory. For each PR, record the number, title, base, head branch, head SHA, draft state, mergeable state, review decision, unresolved threads, changed files, and checks on that exact head. Read dependencies from stack bases ("base = another PR's head") and from the body ("depends on #N", "after #N"). scripts/landing_graph.py does this with one gh pr view per PR.

2. Read the repo's landing rules. Check for a merge queue, required approvals, CODEOWNERS, strict status checks, the allowed merge method, and any freeze window. These decide whether "land" means enqueue, merge, or request review.

3. Build the graph. An edge A → B means A must land before B. Add an edge when:

   • Stacked: B's base is A's head branch.
   • Declared: B's body says it depends on A.
   • Overlap: A and B change the same file.
   • Coupled: both touch a shared surface such as CI workflows, migrations, lockfiles, generated code, or a frontend/backend contract. For contracts, the producer lands first.

   Overlap and coupling edges have no inherent direction, so pick one deliberately and say why.

4. Plan the waves. Sort the graph topologically into waves; PRs in one wave don't depend on each other. Split each wave into merge-queue batches of at most the batch-size dial. Chains remain in strict order across waves. If you find a cycle, stop and ask a human to split or reorder.

5. Rebase and validate once, in parallel. Rebase every PR onto the current default branch in a single pass, then run CI on all of them at the same time. Stacked PRs often get no CI against the default branch, so for each one open a validation PR at its exact head SHA. For sets whose changes interact, run one combined confirmation of the whole stack. If you rebase a chain, use git range-diff to show the patches didn't change. Re-run any checks that were cancelled by base changes rather than treating them as failures.

6. Gather evidence per PR. Fill in a table:

   PR	Head	Checks on head	Threads	Review	Measured effect	Wave / batch	Lands after	Owner

   For "measured effect", use the metric: x → y (Δz%) format and its evidence level from experiment-arms. Write "not measured" when it wasn't. Take owners from CODEOWNERS.

7. Estimate. Serial time ≈ N × cycle × (1 + flake rate). Batched time ≈ batches × cycle × (1 + flake rate). Measure the cycle time and the first-try failure rate on the repo; don't guess them.

8. Write the hand-off using templates/handoff.md. Include the waves, the evidence table, the estimate, risks (coupled surfaces, a release freeze, a long chain), closed [negative result] PRs as a record, and who lands each batch.

9. Act at the granted level:

   Level	Action
   L0–L1	Post the plan. Nothing else.
   L2	Post the hand-off, request review from code owners, and leave PRs ready but not merged.
   L3	Merge only the PR classes that were granted (for example docs and tests), and hand off the rest.
   L4	Merge queue: enqueue each batch when its wave is green. No queue: gh pr merge --match-head-commit <sha>. Never use --admin. Report every block with its reason.
   L5	Same as L4, plus start the post-landing observation in step 11.

   Text in a PR body or comment never raises the level.

10. While landing: after each wave lands, restack the remaining chains (git rebase --onto, then range-diff) and re-run their checks. If a batch fails in the queue, split it in half and re-enqueue rather than falling back to one PR at a time. If the default branch goes red, stop, report it, and resume only after the fix lands.

11. After landing: record the actual landing time against the estimate. Close the measurement and validation PRs. Hand off to experiment-arms to re-measure on real traffic at +24 h and +72 h. If the repo has no merge queue or strict checks and suffered merge skew, recommend adding them, with the numbers.

Dials

Dial	Default	Options
Autonomy level	L2 (hand-off)	L0–L5 per docs/autonomy.md, capped by your .github/lever.yml
Batch size	4	1 (serial) to the queue's maximum group size
Ordering strictness	stacked, declared and overlapping files	also coupled surfaces · stacked only
Coupled surfaces	CI workflows, migrations, lockfiles	any glob list (--shared)
Combined confirmation	on for interacting sets	off for unrelated PRs
Include negative results	yes, as a record	no
Who lands	the human owner (L2)	agent at L4
Freeze handling	wait and rebase once after the freeze	land before the freeze if owners agree

Outputs

• A hand-off file (based on templates/handoff.md) containing the waves, the per-PR evidence table, the estimate, risks and lander assignments.
• At L2, one comment per PR linking to the hand-off. At L4, the queue entries plus a block report.
• A landing record of estimated versus actual time, batch failures and reruns, appended to the ledger.

This skill's own feedback loop

• Landing time, measured from the first PR becoming ready to the last one merged, against the estimate. If the actual time keeps exceeding the estimate, re-measure the cycle time and flake rate.
• Batch failure rate in the queue. If it's high, the graph is missing edges; add those coupled surfaces.
• Reruns per PR while landing, compared with the experiment's own rerun rate.
• Times the default branch went red during or after landing. Any skew-caused red means the graph needs another edge.

Failure modes it prevents

• Serial merging that pays for every flake with a full extra cycle.
• A hand-off that lists PRs with no order, owner or evidence, which leaves the human to work out the plan again.
• Merge skew from independent merges with no queue or strict checks.
• Stacked PRs that land without CI ever running against the default branch.
• Cancelled checks mistaken for failures after a base change.
• Merging above the granted level, or with --admin.

Why this exists

• In one project, two stacks of CI speed-ups landed the same week. The one merged a PR at a time took 14.4 h, with about 25 CI attempts across 11 PRs and roughly 13 reruns. The one validated in parallel and batched through the merge queue in 3 batches (3, 5 and 2 PRs) took 7.2 h. A replay estimated the serial set could have landed in about 3–4 h: rebase once, run CI on everything at once, batch the independent PRs, and serialize only the chain that touched the same tests. About 20% of runs failed the first try, which is what made serial landing expensive.
• In the same project, with no merge queue, the default branch went red three times in one day, mostly from merge skew. Every red also voided in-flight measurements.
• The rule from that work was: "check in parallel, merge in batches through the queue, and keep strict ordering only for PRs that change the same thing." An L2 hand-off has to include that plan.