stella/ai-shared/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.

5. Run Proportionate Checks

Use the repository's canonical verification command for code changes. Start with focused checks while iterating, then run the CI-equivalent command before push when the task and machine allow it.

For documentation or skill-only changes, run their owning generators and validators, formatting verification, and git diff --check; do not run unrelated application suites as ritual. Let pre-push hooks run their affected gates.

Honor explicit constraints on heavy local checks. Record what was skipped and rely on CI rather than silently invoking equivalent work another way.

6. Apply Security Review by Risk

Always inspect for secrets, private identifiers, unsafe public wording, and local paths. Run the repository security-audit workflow when the change touches a security boundary or the user requests it. Fix validated in-scope high-risk findings before publication and follow the repository's public-disclosure policy.

7. Commit and Push Safely

Use focused commits that follow repository conventions. Push a new branch normally. Use --force-with-lease, never plain force, only after intentionally rebasing a published branch. For a stack, submit every layer and verify each PR targets its parent.

Refresh HEAD_SHA from the final local commit immediately before pushing. Push the explicit local branch to its resolved HEAD_REPO destination, then verify the remote branch resolves to that SHA; do not let an implicit push target select the repository or branch.

8. Open or Update Review State

• An explicit draft request creates or preserves a draft.
• An ordinary request to open a complete PR creates it ready for review.
• Keep a PR draft only when requested or when the change is knowingly

incomplete; state the reason.

Write a concise title and body describing only the visible implementation. Follow repository rules for attribution and public context. Do not add a test plan unless requested.

When the change alters what a user sees, add screenshots (before and after for a changed screen) through the repository's documented attach command, which checks that every image shows only fixture data. A repository without one gets no screenshots: never attach an image with gh --attach directly, since attachments on a public repository are public. Skip this when nothing visible changed.

For an existing PR, update only PR_NUMBER in BASE_REPO; never rely on the checkout's implicit repository or branch selection. For a new PR, pass the resolved base repository, base branch, and head repository and branch explicitly. After any create or update, refetch that exact PR and require its repository identity and headRefOid to equal BASE_REPO and the pushed HEAD_SHA before reporting it.

Report the URL, readiness, checks run or skipped, and any blocker. Do not begin bot monitoring, merge, or deployment unless the user requested that broader workflow.