Branch Finishing

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

1. 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
2. Resolve conflicts locally. Before pushing a rebase, resolve every conflict locally and run the full test suite; never push a branch with unresolved markers.
3. 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.
4. 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

5. 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.
6. 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.
7. 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.
8. 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

9. 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.
10. 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

11. 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.
12. 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.
13. 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

14. 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.md
• skills/review-deployment/SKILL.md