GitHub Pull Request Workflow

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.

Prepare a GitHub pull request a reviewer can land without follow-up questions: branch hygiene, reviewable commit shape, a high-signal title and body, verification evidence, screenshots for UI work, and clean replies to review comments.

This is a bundled catalog skill — part of the bundled baseline kit. For how to install, audit, update, assign, and reset catalog skills, see the Skills reference.

When to use

• You're 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 or verification).

When not to use

• The change isn't functionally complete yet — finish the work first.
• The repository uses a non-GitHub forge — adapt to that forge's conventions.

Catalog metadata

File inventory

Full skill definition

Skill frontmatter

• name: github-pr-workflow
• description: 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.
• key: paperclipai/bundled/software-development/github-pr-workflow
• recommendedForRoles:
  • engineer
• tags:
  • github
  • pull-requests
  • code-review
  • release

Skill instructions

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.

See also

• Bundled skills — all bundled catalog skills grouped by category.
• Skills reference — file shape, install pipeline, catalog browse/install/audit/update/reset, assignment, and troubleshooting.
• App-shipped catalog — how bundled and optional catalog skills are versioned and kept current.
• Skills guide — the UI walkthrough and built-in catalog overview.