--- name: land-stack description: > Land (queue/merge) a stacked pull request safely, on any repo using a PR-stacking workflow (Mergify, Graphite, or similar). Trigger when asked to land, merge, ship, or queue a PR or PR stack. Enforces that you act only on SHA-verified PR numbers — never a PR found by branch name. --- # land-stack Use this skill whenever the user asks to **land / merge / ship / queue** a PR or a PR stack. Generalized from a real incident in a repo using Mergify Stacks — the specifics below (label names, `gh` commands) assume that tooling, but the discipline transfers to any stacking workflow: adapt the discovery/merge commands to whatever queue tool the repo actually uses. ## Hard rule **Never identify the PR to land by branch name.** Two different PRs can share a branch name (an auto-generated workflow branch PR and the intended stack PR). You must land by **SHA-verified PR number**, and every PR must pass a guard before any write (label, thread-resolve, queue, merge). ## Steps 1. **Resolve PR numbers, bottom of stack first.** If the user gives numbers or URLs, use those. If they do not, make a best-effort read-only discovery pass and suggest the numbers yourself: - Enumerate open PRs broadly, e.g. `gh pr list --state open --json number,baseRefName,headRefName,headRefOid,title --limit 100`. - Filter to the repo's actual stack-branch naming convention (e.g. `stack/`). - Prefer candidates whose `headRefOid` exists in the local clone, so the code is actually available for review. - Order the stack by base/head links: the bottom PR targets the trunk; each later PR targets the previous PR's head branch. - Detect whether two or more open candidates share the same `headRefName`. If they do, present the exact bottom-up PR numbers and ask the user to confirm them before landing. This is the only discovery case that requires confirmation. - If every candidate `headRefName` is unique, run the guard on the suggested sequence and, when it passes, land it without an additional confirmation. Never discover by branch name. Do not run `gh pr list --head ` to decide what to land — that is the unsafe path this skill exists to prevent. 2. **Verify with a guard before any write.** Check, for each PR: head SHA exists in the local clone (it is the code you reviewed), head branch matches the repo's real stack-branch convention (rejects raw workflow/auto branches), the PRs form a proper stack (each base is the previous head; the bottom's base is the trunk), and all are OPEN. If any check fails, stop and resolve the mismatch with a fresh discovery pass — do not work around it. The check is `scripts/verify_stack.py` in this skill (see below); run it and paste its output rather than reasoning through the four checks by hand. ```sh python3 scripts/verify_stack.py --repo --trunk --git-dir ... python3 scripts/verify_stack.py --repo --discover # suggest stacks; exit 3 = confirm with the user ``` Exit 0 means every check passed for that exact order. Exit 1 lists the failing check per PR. The script never calls `gh pr list --head`. Then check each PR is not superseded before rebasing it or resolving its conflicts. A branch behind its base still lists differing files; that listing does not say which way they differ. Fetch the trunk, then run the catstack gate `scripts/ci/check_branch_not_superseded.py` (the skill directory links into the catstack checkout, so it sits three levels up from the resolved skill path) and paste its output: ```sh git fetch origin python3 "$(realpath ~/.claude/skills/land-stack)/../../../scripts/ci/check_branch_not_superseded.py" '#' --base origin/ ``` - Exit 0, LIVE: the PR carries work the trunk lacks; rebase it if needed and go on. - Exit 3, SUPERSEDED: do not rebase or resolve conflicts, since that would revert landed work. Close the PR with a comment naming the PRs that superseded it (find them in `git log --oneline ..origin/` over the files it touches). - Exit 2 or any other code, UNCHECKED: the check did not run. Fix what it names (fetch, unshallow, correct the ref) and rerun; never treat it as LIVE. 3. **Land bottom-up.** Merge the bottom PR, wait for it to actually merge, then retarget the next PR's base onto the trunk before merging it. Repeat up the stack. A base change can report an unsettled/unknown mergeability state immediately after — wait briefly and re-check before merging, don't merge on a stale read. After every queue write (a label, a `@mergifyio queue` comment, a merge command), read the queue's own state before saying anything is queued: ```sh python3 scripts/verify_stack.py --repo --queue-state ... ``` Exit 0 means each PR is merged or queued. Exit 1 names a PR the queue never took. Exit 2 means its state could not be read, which is not a pass. A queue label satisfying a rule's conditions is not the same as queued: Mergify reports `Merge queue is ready` until a `@mergifyio queue` comment (or the dashboard) actually queues the PR. 4. **Never batch merges without checking each result.** A merge command can look silent on both success and some failure paths; a silent-looking run is not proof of a merge. ## Do not - Do not bypass the guard by hand-adding a bypass label or merging directly to skip a broken check — if the queue is unhealthy, that's a different, riskier operation that needs its own explicit authorization, not this skill. - Do not resolve review threads to unblock a merge by default. Decision tree: - **Automated review thread under an explicit babysit-until-merged job** (for example CodeRabbit): after the current head addresses the thread (or the thread is outdated), resolve it yourself via the GitHub review-thread API. Do not bounce that to the user. - **Deferral required for human reviewer threads:** resolve only when the user has decided to defer those findings; record the deferral on the PR. This rule alone never authorizes resolving a human thread. - **Otherwise leave the thread open:** when there is no babysit-until-merged job, or the head does not address the thread, leave it open. - Do not act on a PR whose head SHA is not in your local clone. ## Prove state before reporting it Before telling the user a PR is merged, queued, blocked, or failing CI, re-run the exact status query in that same turn — do not repeat a status you checked earlier in the conversation. "Merging" is not "merged"; a queued PR can still fail a re-run of the full suite. ## Why this exists A raw workflow-branch PR shared a branch name with the intended stack PR. Landing "the PR on this branch" by name queued the wrong PR. The guard makes that mistake fail closed instead of merging silently.