---
name: pr
description: >
  Route pull request work from branch to merge. Use for opening a PR or pull request, writing or
  polishing PR titles/descriptions, addressing review comments including Greptile bot feedback,
  fixing GitHub Actions checks, merging PRs, and GitHub stacked PRs with `gh stack`. Does not
  organize local uncommitted changes; use commit for local commit grouping.
argument-hint: "[open | polish | comments | ci | stack | merge | loop] [PR# / url]"
allowed-tools:
  Bash(gh:*), Bash(git:*), Bash(scratchpad:*), Bash(python:*), Bash(python3:*), Read, Edit, Write,
  Grep, Glob, Task, Agent
metadata:
  short-description: GitHub PR lifecycle router
---

# PR

Route pull request work to the smallest fitting path. This is the PR front door; it does not replace
`commit` for local commit grouping.

## Routing

If the request names `open`, `polish`, `comments`, `ci`, `stack`, `merge`, `loop`, or a PR
number/URL, use that route. Otherwise infer the smallest fitting route from live state.

## Core Rules

- Start read-only. Identify the repository, branch, local `HEAD`, PR head SHA, base, actual diff,
  checks, reviews, and stack membership before recommending or mutating anything.
- Tie every review and check claim to the PR's current `headRefOid`. After any push or restack,
  discard the old snapshot and re-read PR metadata, checks, and review state.
- Local commit organization belongs to `commit`; GitHub publication and lifecycle work starts here
  only after the intended commits are ready.
- Use `gh` for GitHub state and mutations, including native stacked-PR mechanics through the
  official `github/gh-stack` extension.
- Pushes, force-pushes, PR creation/editing/readiness changes, comments/reviews, thread resolution,
  comment deletion, check reruns/cancellation, auto-merge, and merge all require authorization; a
  request to inspect, review, diagnose, or propose does not grant it. Preview the exact branch,
  base, title/body, affected PRs, expected head SHA, and command first — `gh pr create --dry-run`
  may still push, so it is not a read-only preview. `--force`, `--admin`, and branch deletion need
  their own authorization; prefer `--force-with-lease` for an authorized history rewrite.
- An approved delivery plan (`delivery`) carries standing authorization for the mutations it
  enumerates within a lane's scope; verify the worktree branch, PR head, and locked base against the
  lease before each mutation, and never merge, cancel checks, or delete comments or branches under
  it.
- Greptile policy — state selection, freshness, nudges, and cleanup candidates — lives in
  [greptile-bot](references/greptile-bot.md) and [greptile-loop](references/greptile-loop.md). Read
  one before acting on bot review state.
- The body validator rejects hand-written stack topology and checks nothing else. Write the proposed
  body to a file and run `python scripts/validate_pr_body.py <body-file>` before `gh pr create` or
  `gh pr edit` whenever the PR belongs to a stack or its body mentions another PR at all. The script
  owns the exact rejection set and runs instantly, so when in doubt run it rather than reasoning
  about which forms it catches. Do not publish when it rejects the body.
- Every non-trivial body must pass the artifact-first compression gate in
  [pr-writing](references/pr-writing.md) before its first publication. Treat "make it less wordy" as
  a drafting failure caught here, not a later polish route.
- For web UI work, treat representative final-state screenshots as part of PR readiness. See
  [pr-writing](references/pr-writing.md) for what to capture and [open-pr](references/open-pr.md)
  for the upload flow.

## Decision Tree

1. **Local changes are not committed**
   - Use `commit` first.
   - Return here after the branch has clean commits.

2. **Need a branch, PR, title, or description**
   - Read [open-pr](references/open-pr.md).
   - For title/body details, read [pr-writing](references/pr-writing.md).

3. **Open PR needs readability polish**
   - Read [pr-writing](references/pr-writing.md).
   - Update title/body or add sparse inline comments only when helpful.

4. **Open PR has Greptile or human review comments**
   - Read [review-comments](references/review-comments.md). Default is a single triage pass.
   - Use `python scripts/fetch_comments.py`.
   - For GraphQL reply/resolve details, read [github-graphql](references/github-graphql.md).
   - **Iterate-to-5/5 loop** (only when asked: `loop` / `until 5/5` / `greploop`): read
     [greptile-loop](references/greptile-loop.md); use `python scripts/greptile_state.py`.

5. **Open PR has failing GitHub Actions checks**
   - Read [fix-ci](references/fix-ci.md).
   - Use `python scripts/inspect_pr_checks.py`.
   - Treat non-GitHub Actions providers as external URLs only.

6. **Work should be split into dependent PRs or current PR belongs to a stack**
   - Read [stacked-prs](references/stacked-prs.md); it owns native GitHub stack policy and CLI
     mechanics.

7. **Ready to merge**
   - Single PR: read [merge-pr](references/merge-pr.md).
   - Stack: read [stacked-prs](references/stacked-prs.md).

## Discovery Commands

Run the relevant subset:

```bash
git status --short --branch
git remote -v
git rev-parse HEAD
gh repo view --json nameWithOwner,defaultBranchRef
gh pr status --json number,url,title,headRefName,headRefOid,baseRefName,isDraft,state,reviewDecision,statusCheckRollup,updatedAt
gh pr view <number-or-url> --json number,url,title,body,headRefName,headRefOid,baseRefName,state,isDraft,mergeable,mergeStateStatus,reviewDecision,statusCheckRollup,updatedAt
gh pr diff <number-or-url> --name-only
```

Compare local commits to the actual base after identifying it:

```bash
BASE=$(gh pr view <number-or-url> --json baseRefName -q .baseRefName)
git fetch origin "$BASE"
git diff --stat "origin/$BASE...HEAD"
git log --oneline "origin/$BASE..HEAD"
```

Fetching changes local remote-tracking refs but not GitHub state; do it only when a current local
comparison is needed. For a read-only GitHub review, `gh pr diff` is sufficient.

For stacks:

```bash
gh stack view --json
gh stack sync --help
git worktree list
```

## Output

Report the selected path; repository/PR; inspected head SHA; actual diff scope; review/check
freshness; authorized mutations performed (or explicitly state none); validation; stack state; and
remaining blockers or cleanup handoff. For UI work, report whether screenshots were included,
unnecessary, or blocked. Never imply that green state from an older SHA applies to the current head.