merge

Files (6)

• SKILL.md
• openai.yaml · agents/
• control-trigger-evals.json · evals/
• evals.json · evals/
• heldout-trigger-evals.json · evals/
• trigger-evals.json · evals/

SKILL.md (first lines)

# Merge pull request

Carry the current request's change through a pull request, verified merge, and
safe local cleanup. Complete the necessary commit, synchronization, publication,
and PR work, using the `pull` skill for base synchronization, the `pr` skill to
create or update the pull request, and the `clean-branches` skill for the
cleanup after the merge.

This skill requires `pull`, `pr`, and `clean-branches`. Before doing any work,
confirm each one is installed. When one is missing, stop and report it with
its install command, `npx skills@latest add toy-crane/skills --skill <name>`,
using the project's package manager runner where it pins one.

Start from current remote truth. Preserve unrelated work, commit only the
request's changes as logical Conventional Commits, resolve the named base or
the remote's advertised default branch. If the change or its pull request is
already merged, verify and report that outcome instead of creating another one.
For an existing open PR, fetch its current head and synchronize the checkout
with it, preserving both the observed remote commits and in-scope local work.
If their intended combination is unclear, report the blocker before rebasing
or publishing. Then invoke `pull` with that resolved remote and base before verification,
publication, and creating or updating the ready-for-review PR; it hands back
the checkout rebased onto the fetched base, or the exact blocker when it could
not rebase safely.
Preserve unrelated local work; do not silently
commit, stash, or discard it to make synchronization possible. Resolve conflicts
only when the intended result is established; otherwise keep the work
recoverable and report the blocker. Verify the resulting HEAD before publication,
and publish rewritten history only against the remote PR branch state just
observed.
When the repository's `AGENTS.md` or `CLAUDE.md` carries an `## Issue tracker`
section, read its linked detailed convention when present; legacy inline
conventions also work, without a separate setup skill installation. Without
the section, skip every issue step in this skill. For a configured tracker,
read the `Spec-Folder: docs/specs/<slug>/` trailers from the branch's commits
before merging, while the branch still exists and before a squash can drop
them, and keep those folders for the steps below.

## Create or update the PR with `pr`

After verifying the synchronized HEAD, invoke the `pr` skill with the
resolved remote and base. It publishes the branch and creates the
ready-for-review PR, or reuses the open PR and brings its body and evidence in
line with the final change, including any issue links. Verify before invoking
it, because it publishes. `pr` finishes by handing back the PR URL; here that
is an intermediate step, so continue to the merge below instead of stopping to
report. Invoke it again only when the change itself makes the body outdated,
not when a rebase merely moves the head.

With a tracker configured, confirm on the remote PR before merging what the
reconciliation below reads back: each spec folder the PR carries has its one
issue, named by the `Issue: <tracker>:<id>` line in its `spec.md` and repeated
in the PR body, and the body carries the convention's closing reference only
when the PR delivers implementation. If a linked convention cannot be read,
report the missing information rather than guessing issue operations or
claiming that the issue was linked or closed.

## Merge and clean up

Preserve multiple commits with a rebase merge only when they are meaningful,
independent units worth retaining in the base branch; use a squash merge
otherwise.
If GitHub cannot rebase-merge the pull request because its commits conflict
with the base, repeat the `pull` synchronization above on the PR branch.
Resolve conflicts when the intended combined result
is established, preserve unrelated local work, and publish rewritten history
only against the PR branch state just observed. If intent is unclear or the
remote branch changed unexpectedly, keep the PR open and report the blocker.

After updating the PR head, use only verification of the current head; earlier
CI results do not verify the new commit. Finish relevant checks that GitHub
does not require before allowing a merge. Enable auto-merge only when the
repository permits it, GitHub enforces checks against the current base (for
example, by requiring branches to be up to date or using a merge queue), and
only GitHub-enforced requirements remain pending. Verify that it is enabled,
then wait for the remote to report `MERGED`. If current-base verification is
not enforced, auto-merge is unavailable, or the PR is already mergeable, finish
its relevant CI and required checks and reviews, then merge directly with the
chosen method after rechecking the current head and base. `gh pr merge --auto`
can merge an already-mergeable PR immediately;
it is not a general wait flag. If enabling auto-merge fails, reassess the PR
and use direct merge only after its verification and requirements pass.

While waiting, recheck the current head, base, relevant CI, and required checks
and reviews. If the head or base changes, reassess mergeability and repeat
verification for the current head. A head-match option on the enable request
does not pin later auto-merge to that head; a push by someone with write access
can leave auto-merge armed. Whenever new agent-side or non-required verification
is needed, including after a base-only change or a late check on the same head,
disable pending auto-merge while the PR is still open and verify its removal
before waiting for that verification. Also disable it if merge intent can no
longer be established and work must stop. Before ending with an open PR because
CI failed or a requirement remains unmet, disable any pending auto-merge and
verify its removal. Report those blockers rather than bypassing them. Respect
required checks and reviews without imposing a review request that the
repository does not require, and treat the remote pull request state as the
authority for whether the merge succeeded.

Clean up only after the remote reports `MERGED`, and only the merged branch.
Invoke `clean-branches` with the merged branch, its worktree when one exists,
the fetched base, and the merged pull request's head commit, so a squashed
branch can still be deleted. It runs the project's declared cleanup commands,
removes the worktree and local branch only when nothing still works inside,
and keeps a folder this session works in, a branch with uncommitted changes,
or one with commits the base does not contain. Report its result lines,
including any `holder` process or a branch it kept, beside the verified merge.
Preserve other worktrees, processes, and user changes. When the merged branch
lived in a linked worktree, `clean-branches` leaves the canonical base
checkout alone, so bring it to the merged remote state afterwards using
whatever safe mechanism the current host provides; when the branch was in
the primary checkout, `clean-branches` already did that.

## Reconcile spec folders with the issue tracker

After the remote reports `MERGED`, and only when the repository's `AGENTS.md`
or `CLAUDE.md` carries an `## Issue tracker` section, bring the tracker into
line with the spec folders now on the base branch, using the convention's tool,
issue ID form, and operations. Read both files and use the first section found and its
linked detailed convention when present. Without the section, skip this entirely.

From toy-crane/skills, MIT.

More from toy-crane/skills