---
id: 11467
title: Delay PR review requests until CI is green
state: CLOSED
labels:
  - documentation
  - enhancement
  - ai
  - 'agent-task:review'
  - architecture
  - model-experience
assignees:
  - neo-gpt
createdAt: '2026-05-16T15:06:33Z'
updatedAt: '2026-05-16T15:31:57Z'
githubUrl: 'https://github.com/neomjs/neo/issues/11467'
author: neo-gpt
commentsCount: 0
parentIssue: null
subIssues: []
subIssuesCompleted: 0
subIssuesTotal: 0
blockedBy: []
blocking: []
closedAt: '2026-05-16T15:31:57Z'
---
# Delay PR review requests until CI is green

## Context

PR #11466 / issue #11465 merged the reviewer-side CI fail-fast rule into `pr-review`: reviewers now verify `gh pr checks <N>` before full review, hold while checks are pending, and stop before formal review when checks are failing. The next friction surfaced immediately on the author side: `pull-request` still tells PR authors to assign a primary reviewer and send an actionable `/pr-review` wake immediately after opening the PR.

V-B-A performed before filing:

- `gh pr view 11466 --json state,mergedAt,title,reviewDecision` confirmed #11466 is merged and approved.
- `.agents/skills/pr-review/audits/ci-security-audit.md:10-14` says pending checks must hold review and failing checks must stop before formal review.
- `.agents/skills/pull-request/references/pull-request-workflow.md:229-237` still says authors immediately route a review request, call `manage_pr_reviewers`, and send an actionable primary-reviewer A2A ping.
- Duplicate sweep found adjacent but non-equivalent surfaces: #10905 / Discussion #11237 / #11465 are reviewer-side CI gates; this ticket is author-side review-request timing.

## The Problem

The current author-side handoff wakes a peer into a PR state where the peer is now required to do no full review if CI is pending or red. That creates avoidable context switches, review churn, and repeated re-check loops.

The naive fix, however, is also wrong: delaying all notification until CI is green would violate the mandatory lifecycle A2A notification rule and hide that a PR was opened. The substrate needs a split between visibility and actionability:

- PR opened + CI pending = no-action observer/lifecycle notification.
- CI green on the current head = targeted primary-reviewer request plus GitHub reviewer assignment.
- CI failing = author fixes first; no formal review request except a clearly scoped CI-triage ask.

## The Architectural Reality

- `pull-request` owns author-side PR creation and review-routing behavior.
- `pr-review` owns reviewer-side acceptance/hold/fail-fast behavior.
- `manage_pr_reviewers` is not just metadata; it is GitHub's actionable review-request surface and should not be fired before the reviewer can productively act.
- `add_message` remains mandatory for lifecycle events, so the PR-open notification must remain, but its `Requested action` and `Review role` semantics need to distinguish observer/no-action from primary-reviewer/actionable.
- Progressive Disclosure applies: the main `pull-request-workflow.md` should keep a short routing rule, while the detailed CI-wait/use-time/recheck flow belongs in a sibling payload rather than bloating the workflow map.

## The Fix

Update the `pull-request` skill so author-side review routing waits for green CI before creating an actionable peer review request.

Proposed shape:

1. Add a compact trigger/pointer in `.agents/skills/pull-request/references/pull-request-workflow.md` near §6.2.
2. Add a sibling payload such as `.agents/skills/pull-request/references/ci-green-review-routing.md` with the detailed author-side flow.
3. Require authors to run `gh pr checks <N>` or an equivalent current-head GitHub status query after PR creation and before calling `manage_pr_reviewers`.
4. If checks are pending, send only a no-action lifecycle/observer A2A note and use the wait window to handle open peer review requests or unblock peers, then re-check the author's PR CI.
5. If checks fail, do not request formal review; fix CI first and repeat the current-head check after pushing.
6. If checks pass, choose exactly one primary reviewer, call `manage_pr_reviewers`, and send the existing targeted `/pr-review` A2A request.
7. Preserve explicit exceptions for CI-triage requests, likely infrastructure flakes, P0/human override, and unusually long-running checks, without letting those exceptions become routine review bypasses.

## Contract Ledger Matrix

| Target Surface | Source of Authority | Proposed Behavior | Fallback | Docs | Evidence |
|---|---|---|---|---|---|
| `pull-request` §6.2 review routing | This ticket + #11465/#11466 reviewer-side CI fail-fast | Actionable primary-reviewer assignment/A2A waits until current-head CI is green | No-action observer PR-open notification while CI is pending | One-line map pointer plus sibling payload | Skill text diff + targeted review of example A2A wording |
| `manage_pr_reviewers` invocation timing | GitHub reviewer assignment semantics + `pull-request` invitation layer | Do not call until reviewer can productively run `/pr-review` | CI-triage exception when explicitly requested | Payload procedure | PR author dry-run checklist or fixture text |
| A2A PR-open notification taxonomy | AGENTS mandatory lifecycle notification + flat peer-team routing | Distinguish `Review role: observer` / `Requested action: none` from `Review role: primary-reviewer` / `Requested action: use /pr-review` | If A2A unavailable, document the failure in final/handoff and do not fabricate a review request | Payload examples | Manual verification during next author PR |
| Author wait-window behavior | Operator 2026-05-16 intent + MX friction reduction | Use pending-CI time to clear peer review requests or unblock peers, then re-check own PR | If no peer review requests exist, perform bounded CI polling/hold state | Payload procedure | Acceptance checklist cites live queue survey and re-check result |

## Acceptance Criteria

- [ ] `pull-request-workflow.md` no longer instructs authors to immediately call `manage_pr_reviewers` for every newly opened PR regardless of CI state.
- [ ] The skill explicitly preserves mandatory PR-open lifecycle notification while marking pending-CI notifications as no-action observer/FYI, not primary-reviewer requests.
- [ ] The skill requires current-head `gh pr checks <N>` or equivalent GitHub status verification before actionable reviewer assignment/A2A.
- [ ] Pending CI path tells authors to use the wait window to review/unblock peer PRs when review requests are open, then re-check their own PR's CI.
- [ ] Failing CI path tells authors to fix CI first and forbids formal review requests until a green head exists, except for explicit CI-triage asks.
- [ ] Green CI path preserves the existing single-primary-reviewer routing discipline: exactly one GitHub reviewer assignment and one targeted `/pr-review` A2A request.
- [ ] Long-running/pending-check behavior is bounded and does not create an infinite idle loop.
- [ ] Implementation follows Progressive Disclosure: concise map change in `pull-request-workflow.md`, detailed procedure in a sibling payload, no `SKILL.md` router bloat.
- [ ] Related docs/examples distinguish observer FYI from actionable primary-reviewer request in exact A2A field wording.

## Out of Scope

- Changing the reviewer-side `pr-review` CI fail-fast rules; #11466 already handled that side.
- Adding a GitHub Actions bot or mechanical status gate.
- Changing the cross-family approval requirement or human-only merge gate.
- Treating green CI as sufficient for approval. Green CI only permits requesting review.
- Broad rewrites of PR handoff, FAIR-band, or post-review-pickup workflows beyond the minimum references needed for this contract.

## Avoided Traps

- **Suppressing all A2A until CI is green:** rejected because lifecycle notifications remain mandatory and useful.
- **Calling `manage_pr_reviewers` early but delaying A2A:** rejected because GitHub reviewer assignment is itself an actionable review request.
- **Busy-waiting for CI:** rejected because peer review requests are often the highest-value use of the waiting window.
- **Making this a `pr-review` change only:** rejected because the mismatch is now on the author-side `pull-request` contract.
- **Inlining the entire procedure into the workflow map:** rejected per Progressive Disclosure; the detailed rule should live in a sibling payload.

## Related

- #11465 / PR #11466 - reviewer-side CI fail-fast review gate.
- #10905 - original CI/security audit extraction for `pr-review`.
- Discussion #11237 - AI review assertion compliance under CI state.
- `.agents/skills/pull-request/references/pull-request-workflow.md` §6.2.
- `.agents/skills/pr-review/audits/ci-security-audit.md`.

Origin Session ID: 6ec143cb-2e5b-4964-94d6-eb28cb25bde2

Handoff Retrieval Hint: query_raw_memories(query="author-side CI green review routing pull-request skill primary reviewer request pending CI use wait window peer review requests #11466")

## Timeline

- 2026-05-16T15:06:34Z @neo-gpt added the `documentation` label
- 2026-05-16T15:06:34Z @neo-gpt added the `enhancement` label
- 2026-05-16T15:06:34Z @neo-gpt added the `ai` label
- 2026-05-16T15:06:34Z @neo-gpt added the `architecture` label
- 2026-05-16T15:06:34Z @neo-gpt added the `model-experience` label
- 2026-05-16T15:15:40Z @neo-gpt assigned to @neo-gpt
- 2026-05-16T15:15:45Z @neo-gpt added the `agent-task:in-progress` label
- 2026-05-16T15:20:02Z @neo-gpt cross-referenced by PR #11468
- 2026-05-16T15:27:56Z @neo-gpt added the `agent-task:review` label
- 2026-05-16T15:28:08Z @neo-gpt removed the `agent-task:in-progress` label
- 2026-05-16T15:31:57Z @tobiu referenced in commit `4227d6c` - "docs(pull-request): gate review requests on green CI (#11467) (#11468)

Co-authored-by: tobiu <tobiasuhlig78@gmail.com>"
- 2026-05-16T15:31:57Z @tobiu closed this issue

