Open PR

Open PR

Prepare the current change or stack for review without disturbing unrelated work.

1. Resolve Scope and Isolation

Inspect the branch, worktree, status, remotes, applicable repository instructions, and existing PR before changing history. Resolve the base repository first (step 3) and query it explicitly; in a fork checkout, gh defaults to the fork and would miss an upstream PR:

HEAD_BRANCH="$(git symbolic-ref --quiet --short HEAD)" || {
  echo "detached HEAD; cannot identify a pull request branch" >&2
  exit 1
}
HEAD_SHA="$(git rev-parse --verify HEAD)"
git status --short
: "${BASE_REPO:?set BASE_REPO to the resolved owner/name base repository}"
: "${HEAD_REPO:?set HEAD_REPO to the resolved owner/name head repository}"
PR_CANDIDATES="$(gh pr list --repo "$BASE_REPO" --head "$HEAD_BRANCH" \
  --state open \
  --json number,state,isDraft,headRefName,headRefOid,headRepository,baseRefName,url)"

Resolve BASE_REPO before the query and resolve HEAD_REPO from the branch's configured push remote. Do not guess either identity from an account name. Filter PR_CANDIDATES to entries whose headRepository.nameWithOwner equals HEAD_REPO and whose headRefOid equals HEAD_SHA, then accept exactly one match and assign its number to PR_NUMBER. An empty candidate list means no open PR exists. A missing repository identity or head SHA, more than one exact match, or a detached or otherwise ambiguous local branch must stop the workflow before any candidate's base is used. A non-empty list with no exact match belongs to another head and is not this checkout's PR. --head filters by branch name alone, so matching only the owner is insufficient: an organization can own multiple repositories in one fork network.

Authentication, network, or repository errors must remain visible and stop the workflow before history changes or publication.

Never prepare a PR in a dirty shared checkout. If the checkout is on the default branch, detached, has unrelated changes, or spans repositories or submodules, move the intended work to a clean worktree with a concise inferred branch name. Transfer only owned commits or hunks; do not stash, reset, or silently include unrelated files. Ask only when ownership cannot be determined safely.

Follow the repository's rerere policy. Review every replayed conflict resolution before continuing.

2. Bootstrap Before Trusting Failures

Confirm the repository toolchain, dependencies, submodules, generated sources, and expected environment links exist in the isolated worktree. Run the normal setup flow when they do not, then retry the same check. Missing tools or modules are not product regressions. Keep setup-only lockfile or generated churn out of the PR.

3. Rebase the Correct Layer

Resolve the actual base branch and repository rather than assuming origin/main. Check gh extension list before invoking the optional github/gh-stack extension. If it is installed and gh stack view identifies a stack, use gh stack rebase and review each layer against its parent. If the extension is absent or the branch is not stacked, use ordinary Git; do not install an optional extension merely to prepare a normal PR.

For an existing PR, read its metadata from the exact match rather than the checkout's implicit repository context:

PR_METADATA="$(gh pr view "$PR_NUMBER" --repo "$BASE_REPO" --json number,baseRefName,headRefOid,headRepository,url)"

Treat the explicit BASE_REPO as the base repository and reject a response whose PR number, head repository, or head SHA no longer matches the identity established in step 1. Match BASE_REPO to a configured Git remote, fetch the PR base from that remote, and rebase onto the fetched base. If no configured remote matches, fetch the base repository URL directly and rebase onto FETCH_HEAD; do not add or rewrite remotes silently.

For a branch without a PR, prefer its configured upstream remote and that remote's default branch. Fall back to origin only when no upstream is configured, then resolve the remote default through its symbolic HEAD or repository metadata. Fetch immediately before rebasing.

Resolve deterministic conflicts directly. Ask when competing resolutions would change behavior or discard work whose ownership is unclear.

4. Review the Actual Change

Read applicable instruction files, then inspect the complete semantic diff and changed canonical sources. For generated artifacts, review their source in full and inspect the generated delta for drift; do not reread large mechanical copies.

Check for accidental files, invalid states, authorization and disclosure boundaries, missing generated/i18n synchronization, duplicated capabilities (an existing owner the change bypasses; consult the repository's ownership map, such as docs/module-ownership.md, and its shared packages), validation of data a boundary already validated, migration compatibility, performance, replay safety, and tests that cover real failure modes. Fix confirmed defects before publishing.