Add maintainer-review skill for PR code review#65981
Merged
Merged
Conversation
potiuk
requested review from
amoghrajesh,
ashb,
bugraoz93,
choo121600,
ephraimbuddy,
gopidesupavan,
jason810496,
jedcunningham,
jscheffl,
kaxil,
shahar1 and
vatsrahul1001
as code owners
boring-cyborg
Bot
added
area:dev-tools
backport-to-v3-2-test
choo121600
approved these changes
Apr 28, 2026
potiuk
changed the title
Adds `.github/skills/maintainer-review/` (with the symlink at `.claude/skills/maintainer-review`) — the deep-review counterpart to `pr-triage`. Where triage decides *whether* to engage with a PR (draft/comment/close/rebase/rerun/mark-ready/ping), this skill walks a maintainer through actual code review: read the diff, apply the project's review criteria (`.github/instructions/code-review.instructions.md` + `AGENTS.md` + any per-area `AGENTS.md` discovered along the touched paths), optionally run a locally-configured adversarial reviewer (today: the OpenAI Codex plugin), draft an APPROVE / REQUEST_CHANGES / COMMENT review with verbatim findings, and — on the maintainer's confirmation — post via `gh pr review`. Layout mirrors `pr-triage`: - `SKILL.md` — entry point, golden rules, step-by-step. - `prerequisites.md` — `gh` auth, repo access, plugin detection. - `selectors.md` — default `review-requested-for-me` plus filters: `area:`, `collab:true|false`, `team:`, `ready`, `pr:<N>`, `repo:`, `max:`, `dry-run`, `no-adversarial`. - `review-flow.md` — sequential per-PR workflow with prefetch. - `adversarial.md` — second-reviewer integration, including the "assistant proposes, user fires" pattern for slash-command invocation (`/codex:adversarial-review`). - `posting.md` — `gh pr review` recipes, body templates, the AI-attribution footer. - `criteria.md` — pointer + summary checklist of the project's review criteria. `.gitignore` adds the new symlink to the keep-list, alongside `pr-triage`. `.pre-commit-config.yaml` adds the new SKILL.md to the agentic-markdown license-insert exclude (frontmatter must be the first content; the auto-prepend would break it). The `update-breeze-cmd-output` hook regenerates the selective-check output hash on this run because `.pre-commit-config.yaml` changed; including the new hash in this commit so the hook exits clean on next run.
…l names
Three changes to the skill spec, on top of the initial layout:
1. Default selector now also surfaces PRs that **touch files
the maintainer is actively working on**, not just PRs where
the maintainer is a requested reviewer.
- "Active set" = files in the maintainer's open PRs ∪ files
the maintainer has authored commits to on the base branch
in the past `since:<window>` (default 30 days).
- Each PR carries a `Match:` chip in the headline:
`[review-requested]`, `[touches: <path>]`, or `[both]`.
- New tuning selectors: `mine-only`, `requested-only`,
`since:<window>`.
- GraphQL aliased queries do the path-intersection scan in
batches (no N+1).
2. **Rules are linked, not copied.** `criteria.md` was a
summary checklist that paraphrased rules from
`.github/instructions/code-review.instructions.md` and
`AGENTS.md`. Replaced the bullets with section pointers so
the source files stay the single source of truth and
summaries can't drift. `review-flow.md` Step 4 now defers
to those linked sections instead of restating categories.
3. **Agent-agnostic wording.** Dropped Anthropic-specific
model names (Claude / Opus / Sonnet / Haiku) and
plugin-specific references (OpenAI Codex). The
adversarial-reviewer integration is now described as
"another LLM" the maintainer names via `with-reviewer:` or
in their agent-instructions file (`AGENTS.md` first,
harness-specific `CLAUDE.md` as alternate). Findings are
tagged `source: primary | adversarial | both`.
…pproval auto-skip Sequential review of long PR queues was wall-clock bound by per-PR fetch + classify. This restructures Golden rule 1 to keep posting sequential while running analysis in parallel via background subagents on the next PRs in the queue, so the next headline + findings + draft appear instantly when the maintainer confirms the prior one. Lookahead window K defaults to 3 (`lookahead:<N>` and `no-prefetch` selectors added). The subagent contract is read-only — no GitHub mutations, no nested subagents, AI-attribution footer must be emitted byte-for-byte. Subagents take pre-fetched PR data inline because in many harness configurations they don't inherit the parent's `gh` Bash grants. Also adds a viewer-already-approved auto-skip: if the PR's reviews already include an APPROVED from `<viewer>`, the skill skips it rather than stacking a redundant second approval.
- Default selector ("my reviews") = union of 5 signals: review-
requested, touching-mine, codeowner, mentioned, reviewed-before
(triage comments excluded — they live in comments[], not reviews[]).
- Inline review comments are proposed by default with a one-prompt
picker; dropped findings fold into the body's "Smaller observations".
- Every printed PR number is paired with its full HTTPS URL so
URL-aware terminals make it clickable.
- [Y]es at a PR's headline auto-opens the PR via `gh pr view --web`
in parallel with the diff fetch; disable per-session with
no-browser.
- New selectors: codeowner-only / mentioned-only / reviewed-before-only
+ matching no-* flags + inline:off / no-browser.
- Doc: "How to invoke — examples" section with 15 worked invocations.
- Bump dev/breeze/doc/images/output_ci_selective-check.txt md5
(update-breeze-cmd-output hook drift; was failing CI).
potiuk
force-pushed
the
add-maintainer-review-skill
branch
from
76195ea to
5800490
Compare
Contributor
Backport failed to create: v3-2-test. View the failure log Run detailsNote: As of Merging PRs targeted for Airflow 3.X In matter of doubt please ask in #release-management Slack channel.
You can attempt to backport this manually by running: cherry_picker dbf558c v3-2-testThis should apply the commit to the v3-2-test branch and leave the commit in conflict state marking After you have resolved the conflicts, you can continue the backport process by running: cherry_picker --continueIf you don't have cherry-picker installed, see the installation guide. |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Adds
.github/skills/maintainer-review/(with the symlink at.claude/skills/maintainer-review) — the deep-reviewcounterpart to
pr-triage.Where
pr-triagedecides whether to engage with a PR(draft/comment/close/rebase/rerun/mark-ready/ping), this skill
walks a maintainer through the actual code review: read the
diff, apply the project's review criteria
(
.github/instructions/code-review.instructions.md+AGENTS.mdAGENTS.mddiscovered along the touched paths),optionally run a locally-configured adversarial reviewer
(today: the OpenAI Codex plugin), draft an
APPROVE/REQUEST_CHANGES/COMMENTreview with verbatim findings,and — on the maintainer's confirmation — post via
gh pr review.Layout
Mirrors
pr-triage:SKILL.md— entry point, 9 golden rules, step-by-step.prerequisites.md—ghauth, repo access, plugin detection.selectors.md— defaultreview-requested-for-meplusfilters:
area:,collab:true|false,team:,ready,pr:<N>,repo:,max:,dry-run,no-adversarial.review-flow.md— sequential per-PR workflow with prefetch.adversarial.md— second-reviewer integration, including the"assistant proposes, user fires" pattern for slash-command
invocation (
/codex:adversarial-review).posting.md—gh pr reviewrecipes, body templates, andthe AI-attribution footer (per-disposition variant).
criteria.md— pointer + summary checklist of the project'sreview criteria.
Other changes in this commit
.gitignore— add the new symlink to the keep-list,alongside
pr-triage..pre-commit-config.yaml— add the newSKILL.mdto theagentic-markdown
insert-licenseexclude list. Frontmattermust be the first content of the file; without the exclude
the hook prepends a license comment and breaks frontmatter
parsing.
dev/breeze/doc/images/output_ci_selective-check.txt— theupdate-breeze-cmd-outputhook regenerates this on any.pre-commit-config.yamlchange; including the new hash sothe hook exits clean on the next run.
Out of scope
ready) — those stay in
pr-triage.Adversarial-reviewer integration
The skill detects the OpenAI Codex plugin
(
codex@openai-codex) at session start and proposes/codex:adversarial-reviewper PR. Slash commands cannot beinvoked from the assistant side — the skill explicitly uses
the "assistant proposes, user fires" pattern documented in
adversarial.md. Other adversarial reviewers can be wired upthe same way via project- or user-scope CLAUDE.md /
memory entries.
Was generative AI tooling used to co-author this PR?
Generated-by: Claude Code (Opus 4.7) following the guidelines