Skip to content
Skills Library
DevOps & cloud · Automation

archestra-merge-queue

/archestra-merge-queue

Use when asked to add an Archestra PR to the merge queue, monitor it through merge, or diagnose and repair merge-group CI failures. Own the requested PR until merged or an actionable blocker; opening a PR alone does not start this workflow.

Repository
archestra ↗
Licence
MIT
Last repository change
27.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 27.10.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Use when asked to add an Archestra PR to the merge queue, monitor it through merge, or diagnose and repair merge-group CI failures. Own the requested PR until merged or an actionable blocker; opening a PR alone does not start this workflow.

Original author description

Use when asked to add an Archestra PR to the merge queue, monitor it through merge, or diagnose and repair merge-group CI failures. Own the requested PR until merged or an actionable blocker; opening a PR alone does not start this workflow.

How it works

  1. Scope and entry
  2. Monitor the current attempt
  3. Diagnose, repair, verify, requeue
  4. Completion and handoff
Original SKILL.md headings · 142 lines, 1,463 words
SKILL.md preview
---
name: archestra-merge-queue
description: Use when asked to add an Archestra PR to the merge queue, monitor it through merge, or diagnose and repair merge-group CI failures. Own the requested PR until merged or an actionable blocker; opening a PR alone does not start this workflow.
---

# Own the merge queue request

A request to add a PR to the merge queue is an execution task. Enqueue it,
monitor it, and handle failures until GitHub confirms it merged or there is an
actionable blocker. Queue entry, auto-merge enabled, and green PR checks are
intermediate states, not completion. Do not hand routine diagnosis, fixes, or
requeueing back to the developer.

Read [GitHub commands and CI map](references/github-and-ci.md) before acting.
Use the live rules for the actual base branch and the workflows at the tested
commit; the reference describes current `main`, not a permanent required-check
list. Ordinary PR pushes skip most expensive jobs. Those skipped statuses
allow queue entry but do not validate the combined merge-group commit.

## Scope and entry

1. Resolve the exact repository and PR from the request. Record its URL/number,
   base branch, head repository/owner/branch, and current `headRefOid`. Never
   select a PR implicitly from whichever branch happens to be checked out.
2. Apply the user's session authorization and repository instructions. A queue
   request authorizes enqueueing that PR and its eventual queue merge. Carry
   forward already-granted permission to fix, commit, push, and requeue it;
   do not ask again. This skill grants no permissions itself. If explicit
   publication approval required by `platform/AGENTS.md` is still missing,
   prepare and locally verify a concrete patch before asking for that missing
   approval. A request only to create a draft PR does not authorize queue entry.
3. Inspect the PR diff/history, local worktree ownership and WIP, current PR
   policy checks, reviews, draft state, and live branch rules. Preserve other
   developers' branches, worktrees, processes, and uncommitted work. Use a
   dedicated worktree for repairs; read applicable instructions before editing.
   A missing merge-queue rule is a blocker: the same CLI command could otherwise
   merge directly. Do not bypass the queue with `--admin`, change rules/secrets/
   runner variables, approve your own PR, or enqueue other PRs.
4. Run the relevant focused tests using `archestra-dev-testing` and the skills
   for the changed domain. Address fixable PR policy failures. Missing reviews,
   access, a release freeze, or an intentionally draft PR need a concrete blocker
   report, not a bypass.
5. For platform work, run `pnpm enqueue <PR-number> --repo <repository>` from
   `platform/` in a clean checkout of the exact PR head. This runs preflight
   (types, lint, unused exports, white-label copy, frontend/shared unit tests),
   refreshes the remote PR head and live queue rule, and uses GitHub's queue-only
   operation with `expectedHeadOid` to queue only that revision. Do not run preflight
   separately before enqueue: the wrapper already runs it once. Builds, backend
   suites, Rust checks, browser suites and codegen stay in queue CI. Use the
   wrapper once on the finished revision, not on intermediate commits or pushes.
   Fix failures and rerun after changes. Direct GitHub queueing can bypass this
   local command; GitHub does not enforce its preflight result for admission.
   Wait for required PR checks and reviews before invoking it; it stops if GitHub
   rejects queue admission and never enables generic auto-merge. For work outside
   platform, use the guarded GitHub command in the reference after focused local
   validation. Read back queue membership and continue monitoring; queue entry
   is not evidence of a completed merge.

## Monitor the current attempt

Poll PR state and queue membership about every 30–60 seconds while active,
using interruptible waits and concise updates when progress changes. Do not end
the task just because checks are pending or another group is ahead of it.
Honor cancellation immediately; do not create a background/scheduled monitor
or leave one running unless the user requests it.

Keep these identities separate:

- **PR head**: `headRefOid`, the branch commit to verify before pushing/enqueueing.
- **Queue head/base**: `mergeQueueEntry.headCommit.oid` and `baseCommit.oid`, the
  synthetic combination tested by `merge_group`; the head can initially be null.
- **Run attempt**: workflow run ID, `head_sha`, event, and `run_attempt`, plus
  job IDs and their URLs. Fetch all runs/jobs/check pages for the exact queue SHA.

Snapshot the queue entry ID, enqueue time and synthetic SHAs on each poll.
Re-read membership after collecting checks. A different PR head, entry, or queue
SHA invalidates the earlier snapshot; rediscover the current attempt instead
of applying old results to it. Retain failed-attempt evidence even after eviction.
Do not infer membership from a `gh-readonly-queue/.../pr-N-...` name or select
the newest repository run: stacked groups can contain other PRs.

Use PR checks for queue-entry policy, then inspect checks/statuses and every
workflow/job on the current synthetic SHA, including non-required jobs. Match
required contexts and their integration IDs against live rules. Missing,
pending, cancelled, timed-out, or unexpectedly skipped checks need investigation;
a skipped twin or successful aggregate cannot erase another failed job. For
aggregate gates, inspect their underlying shards/test legs and input-detection
results. A legitimate conditional skip must be established from the workflow
and successful gate, not assumed from a green PR rollup.

If auto-merge is enabled but membership is absent, keep watching PR policy and
eligibility. If a queue entry disappears, first refresh PR state: it may have
merged. Otherwise inspect the queue removal reason, actor/time, last queue SHA,
and logs. Distinguish CI eviction, conflicts, timeout, superseded group, and
deliberate human removal; do not automatically undo someone else's removal.

## Diagnose, repair, verify, requeue

For **any failed queue job**, capture the complete failure picture before
changing code: exact SHA/run/attempt/job, failed steps, logs and relevant test
artifacts. Follow aggregate failures to the originating jobs. Inspect each
independent failure, not just the first red gate. If the PR has already merged,
report remaining failures and obtain scope for any follow-up PR.

Classify the evidence and act:

| Evidence | Action |
| --- | --- |
| Reproducible code, lint, build, migration, security, or test failure | Reproduce the failing command/scenario locally, patch the cause, and verify the fix. |
| Failure only on the combined queue commit | Reproduce that recorded synthetic SHA in a disposable detached worktree; compare with the target PR plus current base to isolate the interaction. Patch only the authorized PR. A cause in another PR or base that cannot be fixed within scope is a blocker with evidence. |
| Test intermittency | Reproduce/investigate the failed scenario, fix the race or isolation issue, and run enough focused repetitions to exercise it. A later green run alone does not establish a fix. |
| Evidenced infrastructure/transient failure | Attempt local reproduction where meaningful and record its limits. Verify the outage/failover recovered before one justified retry or requeue for that failure signature. Repeated failure without a new diagnosis/remedy is a blocker. Do not invent a source patch for a runner outage. |
| Cancelled/superseded group | Inspect current entry and run identity; follow its replacement. Cancellation of obsolete runs is not a failure of the current head. An unexplained active cancellation/timeout requires diagnosis. |
| Conflict/queue eviction | Fetch the current base and inspect the removal reason. Resolve conflicts on the authorized PR branch, preserving its intent, then rerun affected checks. Prefer an ordinary merge commit where allowed; never amend or force-push without explicit authorization. Requeue only after the cause is resolved. |
| Permissions, required approval, unavailable environment/logs, or out-of-scope change | Complete safe independent diagnosis, then report precisely what access, decision, or remediation is needed. Do not claim local reproduction or validation happened. |

For a repair, run the original failing check/scenario locally before and after
the patch when the environment permits; pin a behavior regression at the right
test level. Then run the affected suite and relevant lint/type/build checks from
the workflow and domain skills. If exact reproduction is unavailable, document
what was tried and the mismatch; do not substitute an unrelated passing test.
No blind retry loops, removed assertions, skipped tests, weakened gates, or
required-check renames to obtain green status.

Review the final diff and commit a focused fix. Re-read the remote PR head and
verify it still matches the commit the repair was based on before publishing;
inspect unexpected collaborator changes rather than overwriting them. Push
explicitly to the PR's head repository and branch, confirm GitHub's new
`headRefOid` equals the verified local commit, and recheck PR policy. Use the
same enqueue workflow for the new head, then resume monitoring its new
synthetic SHA. Fixable failure is a loop through local verification, publication,
and monitoring, not a stopping point.

## Completion and handoff

Confirm `state: MERGED` with `mergedAt` and `mergeCommit.oid` on the requested
PR. Report its URL, merge commit, and any material unresolved non-gating failure.
Do not equate a completed workflow or an empty queue with a merged PR.

For a blocker or user cancellation, report the PR/head and queue SHA, relevant
run/job links, diagnosis, local reproduction/checks attempted, any pushed fix,
current queue/auto-merge state, and the specific next action needed. Do not
promise monitoring after the turn ends. Stop mutations on cancellation; if
the user explicitly asks to remove the PR or disable auto-merge, perform that
requested action and read back its state.
Files in this package (2)
  • SKILL.md 10 KB
  • references/github-and-ci.md 10 KB

Versions

The database has no other skills named archestra-merge-queue.

Database snapshot: 13.11.2026 · package version f2b4f5e9c34f (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 90archestra-pr-hygiene
    Use when opening or updating an Archestra pull request to write an accurate conventional title and a practical, evidence-based description.
  • 90archestra-dev-investigate
    Use when investigating Archestra bugs or incidents — staging issues, backend 50x errors, Drizzle failed queries, DB connection pressure, deploy regressions, or Kubernetes/runtime symptoms. Orientation only; defers the process to /investigate.
  • 90merge-queue
    This skill should be used when working with GitHub merge queues and branch protection — queue semantics, required checks, strict status checks, auto-merge, and why a merge is blocked.
  • 100graphite-merge-queue
    Operate the Graphite Merge Queue — enqueue PRs via label, dequeue, monitor queue status, and reason about stacked-PR queueing. Use when the user mentions Graphite merge queue, "merge when ready", queueing a PR, dequeueing, fast-track, the merge-queue label, "enqueue", "the…
  • 90pr-autopilot
    Keep one pull / merge request merge-ready - resolve merge conflicts, triage every unresolved review thread, fix in-scope CI failures, re-check live state every pass and pace the next pass with a one-shot cron job. Never merges. Use for /autopilot and "keep PR 42 merge-ready".
  • 100babysitting-pr
    Monitor a pull request for CI failures, review comments, and merge conflicts — then fix them automatically. Use when a PR is open and you want the agent to keep it merge-ready.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.