--- name: github-pull-requests description: Create, inspect, review, update, and safely complete GitHub pull requests with the gh CLI. Use for opening PRs from issue worktrees, checking CI, independent model reviews, addressing feedback, or preparing an authorized merge. compatibility: Requires git, an authenticated GitHub CLI (gh), and Herdr for managed agent workspaces. --- # GitHub pull requests Read [the shared workflow policy](../_shared/github-workflow.md) before acting. It defines the checkpoint, preview, commit, and layer concepts and the authorization each one needs. Apply [agile-engineering](../agile-engineering/SKILL.md) when judging scope and validation. ## Open a pull request Work from the issue worktree, not the primary checkout. Before proposing a PR: ```bash git status --short --branch git diff --check git log --oneline --decorate ..HEAD git diff --stat ...HEAD ``` Run the repository's required validation. Push only the branch you are publishing: the issue branch, or one layer branch of a stack. Draft a PR using the local pull request template and include: - linked issue (`Closes #N` only for complete resolution); - delivered behavior and its value, not a file-by-file change log; - meaningful deviations from the linked issue or accepted design, without retelling either; - each validation command and its result on one short line, including failures, linking lengthy output; - relevant risks, limitations and unverified behavior; screenshots when they prove a claim. Aim for one screen, not a word quota. Link the issue for intent and scope, and evidence for detail. Keep information that changes a review or merge decision; omit empty sections and boilerplate unless the repository requires them. Open it without showing it first when [routine delivery](../_shared/github-workflow.md#routine-delivery) covers the task or the request authorized it (`push it`, `create the PR`): commit, push, and open it without another question. Otherwise show the final title, body, base, and head before `gh pr create`. Prefer `--body-file`. ## Inspect a pull request ```bash gh pr view --json number,title,body,state,isDraft,author,baseRefName,headRefName,mergeable,reviewDecision,statusCheckRollup,closingIssuesReferences,url gh pr diff --name-only gh pr checks ``` Read linked issue context and repository instructions. Do not trust the PR description as proof that code or tests are correct. ## Stacked pull requests One pull request per issue is the default, and no consuming repository has used a stack yet. When a change is worth reading in several units, [stacked pull requests](references/stacked-pull-requests.md) has the layer branch naming, the operator steps on GitHub, the rules for changing a lower layer, and merge and cleanup. Include each layer in the review backlog under the shared policy's [review capacity](../_shared/github-workflow.md#review-capacity) rules, and `finish-issue --delete-branch` removes only the branch attached to the worktree. ## Independent review Create a detached, isolated review worktree. The reviewer runs in a named tab of a workspace this repository already has, so the review sits beside the work it reviews without a new workspace: ```bash node /resolved/pi-clean/scripts/github-work.mjs review-pr --reviewer claude ``` `claude` is the default reviewer and launches Claude Opus 5.5; `--reviewer codex` launches GPT-6 Sol under a `workspace-write` sandbox. Both instruct the reviewer not to spawn native subagents and pass their vendor's flag for it, so a reviewer that needs help asks for a second visible session. Review the full diff for correctness, regressions, security, error handling, maintainability, test quality, and issue acceptance criteria. Judge tests with the questions in [Test what earns its place](../agile-engineering/SKILL.md#test-what-earns-its-place): a request for a test names the failure it would catch, and a finding against a test names its concrete defect or cost, such as that it cannot fail, pins nothing depended on, or duplicates other evidence. Neither is a default finding. Check that the change completes the agreed behavior, including affected callers and configuration, without adding speculative capabilities. Check that the PR makes the value, deviations and unverified behavior clear without repeating the issue. A report that names tests but leaves its claimed outcome unverified needs that gap stated. Hypothetical future needs do not expand scope. For a pull request in a stack, that diff is the layer's own diff against its base branch, with the stack map for context, not the whole stack. Run focused validation when practical. Lead the report with the verdict and the decision it needs, then distinguish: - blocking findings with file/line evidence and a concrete failure mode; - non-blocking suggestions; - questions caused by missing context. The authoring agent must not be the sole independent reviewer. A review that has to judge a new or materially changed design direction follows [the shared design-ownership rule](../_shared/github-workflow.md#delegated-design-ownership): Opus reviews the design, and other reviewers flag unresolved design judgment rather than approving or redesigning it. Do not edit the author worktree. Do not publish comments, approval, or requested changes until authorized. ## Address feedback The author works in the original issue worktree. Re-read each finding, verify it independently, make focused changes, rerun relevant validation, and reply with evidence. Do not dismiss findings solely because checks pass. ## Merge and cleanup Merging always requires explicit user authorization. Immediately before merge, refresh PR state, review decision, and checks. Follow repository merge strategy; do not bypass branch protection. When Martin says a pull request merged, that is the grant to clean up its task without asking again. After merge or intentional abandonment, clean review worktrees first and the issue worktree last: ```bash node /resolved/pi-clean/scripts/github-work.mjs cleanup-pr node /resolved/pi-clean/scripts/github-work.mjs finish-issue --delete-branch ``` Before removing anything, both commands check that every local commit is in a pull request head GitHub reports or in the remote default branch as `git ls-remote` reports it, so squash and rebase merges clean up like merge commits. A clean status, a remote-tracking ref, and `git branch -d` are not that evidence. `--delete-branch` then deletes the branch with `-D`, for the proven tip only, and reports what preserved it. Each command refuses, having removed nothing, on local-only commits, a dirty worktree, an active or blocked agent, a hosted review, a pane working outside the checkout in a workspace it would close, or evidence it cannot obtain. Report a refusal; do not work around it. [The design record](../../docs/reviewable-delivery.md#amendment-routine-delivery-and-verified-cleanup) has the reasoning. Run from the issue's own workspace, `finish-issue` cannot remove the session running it. It runs every check, then opens a visible `# ยท Cleanup` tab in the repository's primary workspace that waits for your pane to settle and repeats the command. Report that tab and stop. Without a single primary workspace it refuses and prints the command to run from the primary checkout once you have stopped. A shared checkout with no worktree, such as pi-clean's feature branch in the primary checkout, has nothing for the helper to remove. Verify the same evidence, then return to the default branch: ```bash gh pr view --json state,headRefName,headRefOid,isCrossRepository # MERGED, , false TIP=$(git rev-parse --verify refs/heads/) # the tip you prove, and the only one you delete git fetch pull//head # objects for the check git rev-list --count "$TIP" --not "$(git ls-remote refs/heads/ | cut -f1)" # 0, or stop git switch && git merge --ff-only / test "$(git rev-parse --verify refs/heads/)" = "$TIP" && git branch -D # a moved branch stays ``` If `git switch` refuses because of uncommitted changes that are not yours, stop and report them. If the last line deletes nothing, the branch moved after the check: report it and keep it. `cleanup-pr` closes the panes whose directory is that review's worktree, closes their tab only when it held nothing else, and closes a workspace only when that workspace's own checkout is the review worktree. The host workspace, the author's tab, another review and any unrelated pane are left alone. It refuses while a review agent is working or blocked. `finish-issue` refuses while its workspace still hosts a review checkout, and names the review to clean up or move first. Stop the preview and any dependency processes you started for it, and close their panes, before cleaning up the worktree. The helper refuses a dirty worktree and a working or blocked agent; it says nothing about other processes, and whether removing the worktree stops a process running in a pane is not documented in `herdr worktree remove --help` and was not tested here. Confirm yours are gone, and never stop a service you did not start or that something else shares. The helper must refuse dirty worktrees. Remote branch deletion is a separate consequential action: report a remote branch that is still there rather than deleting it. `--delete-branch` handles one branch; a stack's other layer branches are removed deliberately, as [the stacked pull requests reference](references/stacked-pull-requests.md#merge-and-clean-up-a-stack) describes.