GitHub Pull Request Workflow
Ship a PR a reviewer can land without follow-up clarifying questions. The aim is high signal in the title and body, evidence the change works, and clean replies when feedback comes in.
When to use
- You are about to open a PR for a change that is functionally complete.
- A reviewer left comments and you need to respond and push fixes.
- A PR has been open more than a day and needs to be brought back into shape (stale conflicts, missing description, missing verification).
When not to use
- The change is not yet functionally complete. Finish the work first; draft PRs that bounce on review are noise.
- The repository uses a non-GitHub forge. Adjust to that forge's conventions; do not force GitHub-isms.
Branch hygiene before opening
- Rebase or merge from the target base so the diff is current.
- Squash WIP commits into reviewable units. Prefer one commit per logical change; do not force one-commit-per-PR if the work is genuinely multi-step.
- Confirm tests, typecheck, and lint pass locally. Note any deliberate skips in the PR body.
- Remove debug prints, commented-out code, and
TODO markers that are not tracked.
PR title
- Imperative mood, under 70 characters.
- Lead with the user-visible change, not the file touched.
Allow CSV export from reports table beats Update reports.tsx.
- If the repo uses an issue prefix convention (
PAP-1234:, [security]), follow it.
- No trailing period.
PR body
Use this structure:
## Summary
- 1–3 bullets describing what changed and why.
## Implementation notes
- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
- Migration or config implications.
## Verification
- The exact commands or steps you ran.
- Screenshots or short clips for UI changes (required if pixels moved).
- Edge cases you exercised by hand.
## Risk and rollback
- What breaks if this is reverted, and how to revert cleanly.
Skip the Risk and rollback section only for clearly trivial PRs (typos, docs).
Verification evidence
- Tests passing in CI is necessary, not sufficient. Reviewers also need to know the change behaves correctly end to end.
- For UI work, include screenshots of the golden path and one edge case. Tag dark and light mode if the project supports both.
- For migrations, include a dry-run plan and reversal steps.
- For performance changes, include a before/after measurement, not adjectives.
Replying to review comments
- Reply on every comment, even with just "fixed in " — silent fixes leave the reviewer guessing.
- Push fixes as new commits while review is active; do not amend during review unless the reviewer agrees.
- If you disagree with feedback, say so with one sentence of rationale and let the reviewer decide. Don't escalate over comments.
- Re-request review explicitly after pushing changes.
Merge checklist
- All required checks green.
- All review comments resolved.
- PR title/body still accurate (update if scope changed mid-review).
- Linked issue moves to
in_review or done per project convention.
- Delete the branch after merge unless it is a long-lived integration branch.
Anti-patterns
- PR description that says "see commits". Reviewers should not need to read the log.
- Mixing refactor and behavior change in the same PR with no separation in the body.
- "Address feedback" commits that bundle unrelated edits. One commit per round of feedback is fine; one commit for everything in flight is not.
- Force-pushing during active review without telling the reviewer.
1---
2name: github-pr-workflow
3description: Prepare a GitHub pull request from a feature branch — branch hygiene, commit shape, title/body, verification notes, screenshots for UI work, and replies to review comments.
4key: paperclipai/bundled/software-development/github-pr-workflow
5recommendedForRoles:
6 - engineer
7tags:
8 - github
9 - pull-requests
10 - code-review
11 - release
12metadata:
13 source: https://skillmd.com/skills/paperclipai/github-pr-workflow
14---
15
16# GitHub Pull Request Workflow
17
18Ship a PR a reviewer can land without follow-up clarifying questions. The aim is high signal in the title and body, evidence the change works, and clean replies when feedback comes in.
19
20## When to use
21
22- You are about to open a PR for a change that is functionally complete.
23- A reviewer left comments and you need to respond and push fixes.
24- A PR has been open more than a day and needs to be brought back into shape (stale conflicts, missing description, missing verification).
25
26## When not to use
27
28- The change is not yet functionally complete. Finish the work first; draft PRs that bounce on review are noise.
29- The repository uses a non-GitHub forge. Adjust to that forge's conventions; do not force GitHub-isms.
30
31## Branch hygiene before opening
32
33- Rebase or merge from the target base so the diff is current.
34- Squash WIP commits into reviewable units. Prefer one commit per logical change; do not force one-commit-per-PR if the work is genuinely multi-step.
35- Confirm tests, typecheck, and lint pass locally. Note any deliberate skips in the PR body.
36- Remove debug prints, commented-out code, and `TODO` markers that are not tracked.
37
38## PR title
39
40- Imperative mood, under 70 characters.
41- Lead with the user-visible change, not the file touched. `Allow CSV export from reports table` beats `Update reports.tsx`.
42- If the repo uses an issue prefix convention (`PAP-1234:`, `[security]`), follow it.
43- No trailing period.
44
45## PR body
46
47Use this structure:
48
49```md
50## Summary
51- 1–3 bullets describing what changed and why.
52
53## Implementation notes
54- Anything non-obvious in the diff: trade-offs, dropped alternatives, gotchas.
55- Migration or config implications.
56
57## Verification
58- The exact commands or steps you ran.
59- Screenshots or short clips for UI changes (required if pixels moved).
60- Edge cases you exercised by hand.
61
62## Risk and rollback
63- What breaks if this is reverted, and how to revert cleanly.
64```
65
66Skip the `Risk and rollback` section only for clearly trivial PRs (typos, docs).
67
68## Verification evidence
69
70- Tests passing in CI is necessary, not sufficient. Reviewers also need to know the change behaves correctly end to end.
71- For UI work, include screenshots of the golden path and one edge case. Tag dark and light mode if the project supports both.
72- For migrations, include a dry-run plan and reversal steps.
73- For performance changes, include a before/after measurement, not adjectives.
74
75## Replying to review comments
76
77- Reply on every comment, even with just "fixed in <commit-sha>" — silent fixes leave the reviewer guessing.
78- Push fixes as new commits while review is active; do not amend during review unless the reviewer agrees.
79- If you disagree with feedback, say so with one sentence of rationale and let the reviewer decide. Don't escalate over comments.
80- Re-request review explicitly after pushing changes.
81
82## Merge checklist
83
84- All required checks green.
85- All review comments resolved.
86- PR title/body still accurate (update if scope changed mid-review).
87- Linked issue moves to `in_review` or `done` per project convention.
88- Delete the branch after merge unless it is a long-lived integration branch.
89
90## Anti-patterns
91
92- PR description that says "see commits". Reviewers should not need to read the log.
93- Mixing refactor and behavior change in the same PR with no separation in the body.
94- "Address feedback" commits that bundle unrelated edits. One commit per round of feedback is fine; one commit for everything in flight is not.
95- Force-pushing during active review without telling the reviewer.