| name | branch-finishing |
| description | Apply when closing out a feature branch — pre-merge checklist, rebase, CI verification, cleanup, and post-merge steps. |
| license | MIT |
| version | 1.0.0 |
| tokens_target | 1400 |
| triggers | ["finish branch","pre-merge checklist","branch cleanup"] |
| loads_after | ["git-conventions"] |
| supersedes | [] |
Sub-Skill: Branch Finishing
Purpose: Ensures every feature branch is cleanly rebased, reviewed, and merged without introducing regressions or leaving stale local state behind.
Rules
Pre-Merge Preparation
- Rebase before merge. Always rebase onto the target branch immediately before requesting merge to catch regressions introduced since the branch was cut. Reference: ERR-2026-024
- Resolve conflicts locally. Before pushing a rebase, resolve every conflict locally and run the full test suite; never push a branch with unresolved markers.
- CI green before review. Ensure all CI checks pass on the latest push before requesting a human review; do not ask reviewers to look at a red branch.
- Self-review diff. Before opening a PR, run
git diff main...HEAD and read every changed line; catch debug prints, commented-out code, and accidental file inclusions yourself first.
Commit Hygiene
- Squash fixup commits. Before merge, squash or fixup any
wip:, fixup!, or tmp: commits so the branch history is clean; use git rebase -i to consolidate.
- Issue closing keywords. Use
Closes #NNN or Fixes #NNN in the PR body so the linked issue auto-closes on merge; never leave issues open manually after a successful merge.
- Changelog update. After any user-visible change, add an entry to
CHANGELOG.md (or the project's equivalent) before marking the PR ready for review.
- Version bump. If the project uses semantic versioning, bump the version in the appropriate manifest file as part of the branch before merge, not as a follow-up commit.
Draft → Ready Transition
- Draft until CI passes. Keep the PR in draft state until all CI checks are green and the self-review is complete; convert to ready-for-review only when the branch is genuinely merge-ready.
- Remove draft status explicitly. Use
gh pr ready <number> to convert from draft; do not rely on reviewers noticing a draft PR that was silently updated.
Post-Merge Cleanup
- Delete remote branch after merge. After a successful merge, delete the remote branch with
git push origin --delete <branch> or enable auto-delete in repository settings; stale remote branches pollute the branch list.
- Delete local branch after merge. After confirming the remote merge, delete the local tracking branch with
git branch -d <branch> to keep the local workspace clean.
- Post-merge verification. After merge, pull
main locally and run the test suite once to confirm the integrated state is green; do not assume CI on the PR branch is sufficient.
Conflict Resolution
- Prefer rebase over merge commits. Avoid merge commits on feature branches; use
git rebase to maintain a linear history unless the team explicitly requires merge commits.
See also
skills/git-conventions/SKILL.mdskills/review-deployment/SKILL.md
