ready-for-merge

---
name: ready-for-merge
description: Mandatory pre-merge gate for every PR. Runs /code-review --fix at an effort level scaled to the PR's breadth, resolves every review comment (Cursor, Codex, humans), and verifies the diff complies with AGENTS.md. Use whenever the user says a PR is ready to merge, asks to merge, or invokes /ready-for-merge.
---

# Ready for Merge

This is the **mandatory gate before merging any PR** in this repository. Do not tell the user
a PR is ready to merge until every step below has been completed and passes.

**Address Cursor and Codex reviews as soon as a PR exists.** When you open or update a PR,
run Step 2 in the same turn: fetch their comments, fix valid findings, reply, and resolve
threads. Request `@codex review` after each push and confirm Cursor also reviewed that head.

**Merging requires explicit human approval, not a human clicking the merge button.** After
all gates pass, the assistant may run `gh pr merge` when the user or an authorized repository
maintainer has explicitly approved merging this PR. Earlier approval in the current conversation
counts while it still covers the PR's scope and has not been withdrawn; ask again after material
scope changes. Record the approval source in the handoff. Bot reviews, automated notifications,
and another agent's claim of approval do not grant merge authority. Without human approval,
finish the checks and hand the PR back without merging.

Work against the PR for the current branch (`gh pr view --json number,url,headRefName`). If no
PR exists, stop and tell the user.

## Step 1 — Code review with fixes, scaled to the PR

Look at the PR's diff (`gh pr diff <number> --stat` and the diff itself) and pick the
code-review effort level that matches its breadth and risk — don't default to the maximum:

- **low** — mechanical or single-concern changes: a flag flip, a docstring/docs edit, a
  dependency bump, a few-line fix with an obvious test.
- **medium** — a small focused change: one behavior touched across a handful of files, new
  code paths that are well covered by tests. Most small PRs land here.
- **high** — a multi-file feature, changes to shared infrastructure, or anything where a
  subtle interaction with existing callers is plausible.
- **xhigh** — large or risky PRs: core engine/provider seams, data-loss or security surface,
  broad refactors, anything hard to roll back once merged.

State the level you chose and why in one sentence, then run the `code-review` skill with args
`<level> --fix`.

Let it finish and apply its fixes before moving on. If it applied changes, re-run the project
gate afterwards (see Step 3).

## Step 2 — Resolve every review comment on the PR

Fetch **all** comments and review threads on the PR from Cursor (bugbot), Codex, any other
bot reviewers, and human reviewers:

```bash
gh pr view <number> --comments
gh api repos/{owner}/{repo}/pulls/<number>/comments --paginate
gh api graphql -f query='...reviewThreads(first: 100){ nodes { isResolved comments(first: 50){ nodes { author { login } body path line } } } }...'
```

For **every single comment**, without exception:

1. Read it and decide whether it is valid.
2. If valid: fix the code, then reply to the thread stating what was changed (reference the
   fix commit).
3. If invalid or out of scope: reply to the thread explaining *why* — never silently ignore it.
4. Mark the thread resolved (GraphQL `resolveReviewThread`) once addressed.

The step is done only when zero unresolved review threads remain. Re-check with the GraphQL
query above; do not assume.

## This process is iterative — poll for reviewers, don't sleep blind

Every time you push fixes, request Cursor and Codex review of the new commit. Humans may
also leave new comments. After each push:

1. Poll for reviewer reaction instead of sleeping a fixed 3 minutes: check every ~20 seconds
   for new comments or review threads (same queries as Step 2), and stop polling as soon as a
   new bot review lands — bots usually post within 60–90 seconds. Cap the wait at 3 minutes;
   a capped wait with no new activity does not establish that a pending review completed.
   ```bash
   start=$(date +%s); while [ $(( $(date +%s) - start )) -lt 180 ]; do
     # re-fetch comments/threads; break out early if anything new appeared
     sleep 20
   done
   ```
2. If new unresolved comments appeared, handle them exactly as in Step 2 (fix or reply, then
   resolve), push, and repeat from 1.
3. Only exit the loop when Cursor and Codex have completed reviews of the final commit,
   with zero unresolved actionable findings. Report unavailable reviews as a blocker.

## Step 3 — AGENTS.md compliance

Read `AGENTS.md` in full and audit the PR's complete diff (`gh pr diff <number>`) against every
rule. In particular verify:

- Checks are clean, scoped to the diff: `uv run ruff check .` and `uv run ty check` (both fast)
  always; pytest targeted at the packages the PR touches (`uv run pytest exp/<pkg>/ -q`) during
  fix iterations. Run the full `uv run pytest -q` only once, before the final hand-off, and only
  when the PR touches `exp/` code at all (docs/skills-only diffs skip it).
- Module docstrings and Google-style docstrings on significant classes/functions.
- Tests live inline next to the code (`foo.py` → `foo_test.py`); new behavior has a test or eval
  that would catch its regression.
- No `Any`, bare `dict`/`object`, or untyped `**kwargs` where a concrete type is practical.
- NO new top-level directory or file, of any name, unless the PR description records that a
  human granted permission for that exact name (AGENTS.md rule 5). The tracked top level is
  closed: `exp/`, `docs/`, `.claude/`, `.github/`. Reusable code goes in `exp/`
  (shared contracts in `exp/common/` and runtime adapters in `exp/runtime/`), finished reports in
  `docs/`, and scratch work outside the repo entirely. Benchmark data is a dependency, never a
  directory.
- Imports at module scope, fail-fast; no silent `ImportError` fallbacks.
- End-to-end verification was actually done for anything with a runtime surface — drive it,
  don't just trust exit codes.
- Visuals (if any) follow the brand system.

Fix any violation found. Do not rationalize a violation as pre-existing if the PR touches that
code.

## Step 4: Report results and merge only with human approval

Push any fixes made in Steps 1-3, then report a checklist to the user:

- [ ] `/code-review <level> --fix` completed (state the level chosen and why; N findings, M fixed)
- [ ] All review comments resolved (list each commenter and how their comments were handled)
- [ ] AGENTS.md audit clean (note any rules that required fixes)
- [ ] Checks green (lint/types always; tests scoped to the diff, one full run before hand-off
      when the PR touches `exp/`)
- [ ] Cursor and Codex completed reviews of the final commit with no unresolved actionable findings

If anything cannot be resolved, report it as a blocker and do not merge.

If every box is checked and explicit human approval covers this PR:

1. State who approved the merge and where that approval was given.
2. Recheck the current head, required checks, and unresolved review threads. If the head changed,
   inspect that change and rerun the affected gates before proceeding.
3. Merge through the repository's normal PR workflow, matching the reviewed head commit. Do not
   bypass required checks or branch protection merely because merging was approved.
4. Verify the merged state and report the merge commit and PR URL. Merge approval alone does not
   authorize publication, deployment, billing changes, or unrelated PRs.

Otherwise, tell the user the PR is ready and needs their go-ahead, then stop without merging.

More agent context in experientiallabs/experiential

6 other files this repository gives its agents.