---
name: shepherd-pull-request
description: Shepherd one pull request or a stacked pull-request chain through scope, guarded publication, independent local mid-sized-model review, authoritative remote Codex Review, exact-head validation, and an authorized merge. Use when opening or updating pull requests, handling local or Codex Review results or rebuttals, propagating stacked branches, deciding merge readiness, or completing a merge.
---

# Shepherd Pull Request

## Authority And Scope

Resolve the repository, live default branch, pull-request number, base branch,
head branch, and exact remote head before acting. Treat live GitHub and remote
refs as authoritative; do not rely on stale local branches or cached review
results.

Keep each pull request to one coherent scope. Move unrelated work to another
pull request when it impedes review. Reuse an existing pull request for the same
head and scope instead of opening a duplicate. Do not close, retarget, merge, or
enable auto-merge unless the user has authorized that action.

When this skill is used from `develop-task`, that skill remains authoritative
for the task issue, tracker issue, and Test or Staging routing. Report exact
pull-request state back to that workflow; do not duplicate tracker or deployment
policy here.

## Create Or Prepare The Pull Request

Before opening or updating a pull request:

1. Read repository contribution instructions and the complete changed scope.
2. Resolve the intended base and remote head. Verify that no collaborator moved
   the remote head before a guarded mutation.
3. Format and validate the cumulative change. Do not claim tests or checks that
   were not run on the exact head.
4. Use the title and standalone body to defend why the current change is
   necessary and safe enough to review. They are reviewer decision aids, not
   advertising or release notes: the code speaks for itself. State the
   governing contract, scope boundary, material tradeoffs or failure modes, and
   exact validation that lets a reviewer judge the change. Avoid promotional
   claims, feature-selling language, line-by-line implementation narration,
   review chronology, branch names, commit ledgers, run logs, and obsolete
   process history.
5. Link the pull request from its owning tracker when `develop-task` supplies
   one.

Codex Review reviews only pull requests whose live base is the repository's
current default branch. A downstream pull request in a branch-based stack is
not Codex-Review-eligible while it targets its predecessor branch. Preserve the
stack for incremental review, but do not treat the expected non-default-target
failure as a code verdict. After the predecessor merges, rebase or retarget the
next pull request to the default branch and obtain a fresh review before merge.

Codex Review rejects draft pull requests before diff preparation. Marking a
draft ready does not itself trigger the canonical workflow; rerun the failed
workflow, synchronize the branch, or reopen the pull request after it is ready.

Do not launch a local reviewer for a commit that has not been pushed. Before
launching one:

1. Guarded-push the commit.
2. Read the pull request from GitHub.
3. Verify that the live head SHA equals the pushed commit SHA.

If any step is incomplete, do not launch a local reviewer. Do not use a
canonical Codex Review result unless its recorded head SHA equals the live head
SHA.

## Post-Push Local Review

After guarded publication and live-head confirmation, resolve the canonical
workflow's Codex Review configuration from that exact tree. Derive the local
pass set from the configured `passes` input; do not infer passes just because
standard or adversarial prompt files exist. If `passes` is omitted, resolve the
default from the referenced Codex Review action version rather than guessing.
Also honor the configured policy paths, pass-specific prompt paths, and extra
instructions. Fail closed when a configured input cannot be resolved.

Launch one independent, read-only local reviewer subagent for each configured
pass. Select its model in this order:

1. Use `gpt-5.6-terra` if it is available.
2. If Terra is unavailable, use `claude-sonnet-5` if it is available.
3. If both Terra and Claude are unavailable, use `glm-5.3` if it is available.
4. If all three named models are unavailable, use another mid-sized model.
Do not select a model by size while any named model is available. Do not use a
shorthand model name. A standard-only configuration gets one standard reviewer;
an adversarial-only configuration gets one adversarial reviewer; a
configuration with both gets two independent reviewers. When more than one pass
is configured, launch all reviewer subagents together in one parallel batch; do
not run them sequentially. Never expose one pass's output to another.

Each reviewer must receive the exact published head SHA and merge-base/base SHA.
Require it to read the repository instructions, every configured policy file,
its configured pass prompt from that exact tree, configured extra instructions,
the current standalone pull-request title and body, the complete merge-base
diff, and enough surrounding production code, schema, and callers to
substantiate findings. Include the latest eligible rebuttal only when the
canonical review configuration includes it. The reviewer must not edit files,
create commits, push, mutate GitHub, trigger workflows, or execute local tests or
mock probes.

Require each reviewer to report:

- the configured pass, exact reviewed head, and base;
- `CLEAN` or `BLOCKED`;
- for every blocker, a file and line, concrete reachable scenario, impact, and
  violated repository invariant; and
- only material non-blocking follow-ups.

Local results never transfer across heads and never override a canonical remote
`ACCEPT` for the same current head. If any local pass returns `BLOCKED`, re-read
the live head and inspect the latest canonical Codex Review status for that exact
head before verifying or fixing the local finding:

- If the canonical remote review is `ACCEPT`, stop or disregard every local
  review, do not change code, metadata, or rebuttal because of a local finding,
  and advance the pull request as-is toward the authorized merge gate.
- If the canonical remote review is missing, queued, pending, in progress,
  failed, or `REJECT`, verify the local blocker against source and the governing
  contract. Address every confirmed blocker, validate the fix, update metadata
  and rebuttal disposition, guarded-push with the exact lease, confirm the new
  live head, and only then relaunch the configured local pass set.

Canonical Codex Review and local reviewers may run concurrently after the push.
If canonical remote `ACCEPT` arrives while local reviewers are still running,
stop or disregard them and move to the remaining merge gates. A local `CLEAN`
does not replace a missing, pending, failed, or rejecting remote review. When
delegating a read-only remote CI monitor, use `gpt-5.6-luna` if it is available.
If Luna is unavailable, use `claude-haiku-4-5` or `glm-5.3-flash`. If all three
named models are unavailable, use another small-sized model. Do not select a
model by size while any named model is available. Bind the monitor to the exact
head and require it to stop and mark all observations superseded if the head
moves.

## Codex Review View

Treat every run as an evaluation of one exact live pull-request head. The
reviewer receives:

- live pull-request metadata, including title, body, base, and head;
- the complete merge-base diff, changed-file metadata, and inert snapshots of
  changed files;
- repository review policy and prompt files from the reviewed merge tree, plus
  centrally selected external-source snapshots when applicable; and
- at most one issue comment: the latest comment whose body begins with
  `/rebuttal` followed by whitespace or the end of the comment.

The reviewer does not receive earlier Codex Review comments, aggregate results,
other issue comments, review bodies, or inline review comments. Therefore:

- Keep the title and body as a cumulative, standalone defense of necessity,
  scope, contract, tradeoffs, and validation. Write them to help the reviewer
  judge the change, not to advertise it or paraphrase code that can be read
  directly.
- A rebuttal comment must begin with `/rebuttal` and stand on its own against the
  current title, body, and changes. It must only justify the current change. Do
  not refer to a previous review, earlier finding, comment ID, or a request to
  reconsider.
- Only the latest eligible rebuttal is visible. Never assume that an older
  rebuttal or surrounding GitHub discussion supplies context.

The canonical review workflow runs for `opened`, `synchronize`, `reopened`, and
`edited` pull-request events. Changing the title or body therefore triggers a
new review when GitHub can synthesize the merge commit. Creating or editing the
latest `/rebuttal` comment re-runs the failed current-head review after the
rebuttal workflow verifies the live head and aggregate rejection. A rebuttal
does not require a branch push.

## Classify Blocking Issues

Do not classify or act on a local blocker until applying the post-push remote
precedence check above. A canonical remote `ACCEPT` for the current exact head
ends local blocker handling and advances the pull request as-is.

Resolve the reviewed head before handling its aggregate `blocking_issues`.
Classify each blocker before acting:

- **ADDRESS:** The blocker identifies a valid defect. Change production code or
  configuration on the same pull request. Never rebut a valid defect.
- **CLARIFY:** The implementation is correct, but the current title or body does
  not state the governing contract clearly enough. Correct the metadata; do not
  make an unnecessary code change.
- **REBUT:** The blocker is unsupported by the current diff or governing
  contract. Use a standalone `/rebuttal` containing only current, source-backed
  justification.

Do not modify production code for non-blocking feedback unless the user asks.
A blocker must be resolved in the current pull request and cannot be deferred to
a follow-up.

## Publish A Review Response

Use this order for every blocker response:

1. Re-read and record the live remote head. For an `ADDRESS`, implement and
   validate the fix, then create the local fix commit.
2. Before any push, revise the pull-request title and body when needed so they
   accurately describe the cumulative changes that will be published. Metadata
   is the clarification surface for a fix commit.
3. Before any push, decide the latest rebuttal's disposition:
   - If nothing needs clarification, do not touch an existing rebuttal unless it
     is inconsistent with the changes or metadata that will be published.
   - If an existing rebuttal remains accurate and relevant, leave it unchanged.
   - If an existing rebuttal is inconsistent and a fix commit will be pushed,
     delete it, explain the resulting contract in the title or body, and do not
     replace it merely to narrate blockers fixed by code.
   - If no fix commit will be pushed, revise the title or body if it does not
     match the current changes, then retain an already-sufficient latest
     rebuttal or post one standalone `/rebuttal` against the current blockers.
   - If a fix commit and a genuine `REBUT` classification coexist, post any
     necessary standalone rebuttal before the push. Do not use it to discuss the
     blockers resolved by the fix commit.
4. Only after all required title, body, and rebuttal actions are complete,
   re-read the remote head and guarded-push with an exact lease. A metadata or
   rebuttal-triggered run on the old head is not evidence for the new head.
5. Re-read the pull request and require the intended base, head branch, exact
   head SHA, title, body, and rebuttal disposition after publication.

If no commit is pushed, rely on the title/body edit or eligible rebuttal to
trigger current-head review. Do not create an empty commit merely to trigger
Codex Review.

## Guarded Pushes And Stacks

Use the remote head observed immediately before publication as the lease value.
Prefer an explicit lease such as
`--force-with-lease=<remote-ref>:<expected-sha>` when rewriting a branch. Stop
rather than overwrite an unexpected remote move.

For a stacked pull-request chain:

1. Update the first changed phase.
2. Rebase every downstream phase onto the new predecessor.
3. Verify that each downstream phase preserves its intended patch and contains
   no accidental scope from another phase.
4. Validate every cumulative head.
5. Complete all required title, body, and rebuttal actions before pushing.
6. Guarded-push every ref, atomically when supported.
7. Re-read every pull request and require its intended base branch and exact head
   SHA.

A push invalidates every prior local review and Codex Review result for the
rewritten head. Never transfer review, build, test, or deployment evidence
across heads.

## Review And Merge Gate

Treat the latest canonical remote Codex Review result as authoritative for the
current exact live head. Remote `ACCEPT` overrides every local result for that
head, including `BLOCKED`, missing, incomplete, or still-running local passes.
Do not require local acceptance and do not modify a remotely accepted head
because a local reviewer disagrees. Advance it as-is toward merge while still
requiring all other mandatory checks, approvals, mergeability, and user merge
authority on that same head.

Do not bypass a missing, queued, pending, in progress, failed, or rejecting
canonical remote review. Until remote `ACCEPT` exists, use confirmed local
blockers as described above; local `CLEAN` alone never authorizes merge. Remote
and local results apply only to their recorded head, and a push invalidates
both.

After repeated `REJECT` results, reconsider the plan against the task contract,
current code, and blockers before resizing the pull request. Split only when the
revised plan has separable coherent scopes; never split to evade a blocker.
Every resulting pull request must independently pass Codex Review.

Before an authorized merge:

1. Re-read the live base, head, draft state, mergeability, required checks, and
   Codex Review result.
2. Require the accepted review head to equal the current remote head.
3. Use an exact-head merge guard when the merge mechanism supports it.
4. Re-read the pull request after the merge and verify the merged state and
   resulting commit before reporting completion.
5. Return the exact merged state to `develop-task` so it can update the tracker
   and route subsequent validation. Do not authorize Production deployment or
   release from this skill.