zoltanmaric/coppersushi / .agents/skills/pull-request
pull-request
VerifiedGuides pull request creation, review, stacking, and local cleanup when a PR merges or closes.
Pull requests
The principle
A PR is a unit of review attention, not a unit of work. The reviewer's attention is the scarcest resource on this project. Scope blowup while working is healthy — it's how exploration happens; the discipline belongs at the review boundary, where the blown-up working set gets refactored into digestible layers. Write big, ship small.
commit-cadence is the enabler: atomic, cohesive commits are pre-cut fault lines, so chopping a PR is mostly distributing existing commits across stacked branches.
Lifecycle protocol
- At PR creation, before marking ready for review, and when reviewing, apply the fission tests:
- The and-test: if one plain title cannot cover every commit without "and", it is at least two PRs.
- The piggyback test: any change that entered as "while we're at it" is a candidate layer.
- When scope grows inside an open PR (a piggyback lands), record it immediately in a "Piggybacks" ledger in the PR body, one line per item stating the verdict: "rides — must be understood with the feature: " or "separable — chop offered". The fission decision at ready-time then reads off the ledger instead of anyone's memory.
- When a test fires, offer the chop into a stack (mechanics below); the user decides. Layers split by "must be understood together", never by file type: a rule or doc whose evidence is the feature's code rides with the feature.
- Every PR body carries the template’s "Architecture delta" and "Unusually complex changes requiring reviewer attention" sections. Use the template’s guiding questions to challenge both the implementation and the requirement: seek a simpler approach, assess whether the requirement justifies the complexity, and consider relaxing or dropping it. Simplify or explain retained complexity and its tradeoff; propose requirement changes explicitly rather than silently dropping agreed behavior. Reviewers challenge the same choices. Write "None" when nothing needs special attention.
- At creation, ready-time and review, check README diagrams against the cumulative implementation; use
system-design-diagramfor updates and the Architecture delta section. - Once a PR is ready for review, watch its review threads and checks while other work continues; stop watching when it becomes draft, merges or closes.
- As soon as you learn a PR merged or closed, remove its local branch and unused worktree. Preserve uncommitted or local-only work and branches still needed by open PRs; report any cleanup blocked by those conditions. Use the worktree manager's archive operation for managed worktrees.
- When a goldfish reviews a PR touching
.agents/or anyAGENTS.md, the critic reads.agents/skills/AGENTS.mdand the vendor guidelines it links before the diff.
Review findings
Review primarily as a Google senior principal engineer: judge whether the PR addresses the right problem, then whether it uses the right architecture. Read the surrounding system and its owning design documents before accepting the proposed framing. Challenge a symptom fix when the cause belongs at a different boundary or level.
Start with folder changes and the resulting tree at the reviewed tip (the cumulative tip for a stack), before file-level diffs. Treat new or moved folders as ownership decisions: justify their purpose against existing homes, inspect their consumers, and keep tests, fixtures and generators with their owners. Check abandoned locations and stale references; distinguish tracked structure from ignored local residue before deleting anything.
Then assess interfaces, data flow, domain models, duplicated rules and dependencies. Compare the proposed design with the simplest credible alternative. For library or framework integrations, verify relevant supported APIs in the pinned version before endorsing custom machinery; state the native option or support gap and any behavior tradeoff. Do not favor a small diff when it shoehorns behavior into an awkward architecture; recommend restructuring when it removes the cause or makes responsibilities clearer. Scale the remedy to the problem, and justify its cost with concrete code and consequences rather than an idealized redesign.
State the architectural verdict and remaining compromises explicitly, even when there are no correctness findings. Ground concerns in specific code, explain their practical effect and name a better direction; do not invent objections to fill a checklist. Check whether this is the right unit of review: propose a split for independently understandable changes, and keep changes together when separation would hide their reasoning.
Check whether raw external representations escape their boundary, or internal callers unnecessarily serialize and reconstruct domain objects.
Run Reaper discovery for what the PR makes unnecessary, including affected material outside its diff. Choose how to handle candidates within the review's authorization: report findings, implement cleanup in the current PR, or offer a separate stacked PR using the fission tests. Apply Reaper's execution and independent-review requirements when implementing cleanup; discovery alone does not start its standalone workflow.
- When addressing a review comment, reply in its thread explaining the change and referencing the commit.
- Keep review findings in chat by default. Post them to a pull request only if the user explicitly asks; first show the proposed comment text and anchors and get approval.
- Post each approved finding as a separate inline review thread on the narrowest relevant changed line, so it can be replied to and resolved independently. If no exact line exists, use the closest relevant changed line. Post a top-level summary only if the user asks.
- Attribute each posted thread with the agent, model version and reasoning effort. If the runtime does not expose a field, say so instead of guessing.
Stacks
GitHub-native stacked PRs (public preview since 2026-07): an ordered chain of branches where each PR targets the branch below it and shows reviewers only its own layer's diff.
Facts
- The bottom branch targets the trunk (
main); every other branch targets the one below. - Merging the top PR merges the whole stack in one click. Merging a mid-stack PR merges it and everything below; PRs above stay open and auto-retarget the trunk, with remaining branches auto-rebased by GitHub.
- Squash, rebase, and merge-commit methods all work; stacks are merge-queue aware, and branch protections still apply.
- Limitations: all branches must live in the same repository (no cross-fork); not supported in GitHub Desktop.
gh stackmetadata lives in.git/gh-stack(local JSON, never committed); interrupted rebase state in.git/gh-stack-rebase-state.
Command map (gh stack, official extension github/gh-stack)
Prerequisite: gh extension install github/gh-stack — official, but not bundled with gh.
submit, push, sync, and link may create or update pull requests without confirmation. merge changes the trunk and requires an explicit request.
init [branches...] [--base <trunk>]— start a stack, or adopt existing branches listed bottom→top.add <branch>/add -Am "<msg>"— new layer on top;-Amstages, commits, and creates the branch in one step.submit— push all branches and create/update PRs with correct bases (opens an editor;--autoskips it but creates new PRs as drafts;--openmarks them ready).sync— fetch, cascade-rebase, push, and prune merged layers; offers resolutions when local and remote stacks diverge.rebase— cascade-rebase after editing a lower layer; pauses on conflicts (--continue/--abort).modify— interactive restructure: reorder, fold, drop, insert, rename (needs a clean tree and linear history).link— declare a stack from existing PR numbers without local tracking.merge— all-or-nothing merge of the stack from the CLI.view,up/down/top/bottom/trunk,checkout— inspect and navigate.
Recipes
- Chop an oversized PR into a stack: create layer branches off the trunk, distribute the existing commits bottom→top (entangled commits need re-slicing),
gh stack init <b1> <b2> …to adopt them, thengh stack submit— it retargets the existing PR's base onto its new lower layer. - New layer on an existing stack:
gh stack add <branch>, commit,gh stack submit. Nevergh pr createor a handgit rebase --ontoinside a stack: the PR gets the right base but joins no stack, and the tracking desyncs — repair withgh stack link <bottom> … <top>. - Fix a lower layer:
gh stack checkout <layer>, commit,gh stack rebase,gh stack push. - Insert or reorder layers: GitHub only grows a stack at the top, so
submitandlinkcannot retarget a stacked PR onto a new layer below it, andinitrefuses on a branch that is already stacked. Rewrite ancestry withgit rebase --ontoand push the rebased branches;gh stack unstack <stack-number>(PRs and branches untouched; the bare form refuses when the stack holds a merged layer);gh pr edit <n> --base <lower>for each PR whose base moves;gh stack link <b1> … <bn>to create the stack on GitHub;gh stack init <b1> … <bn> --base <trunk>for local tracking. - After a partial merge:
gh stack sync --prune.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 319k | Updated | Claude CodeCodex | Verified | Install |