# Branch Finishing

> Apply when closing out a feature branch — pre-merge checklist, rebase, CI verification, cleanup, and post-merge steps.

- Skill: `sordi-ai/branch-finishing` (Agent Skill)
- Install (CLI): `npx skillmds@latest add sordi-ai/branch-finishing`
- Raw SKILL.md: https://api.skillmd.com/api/skills/sordi-ai/branch-finishing/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: sordi-ai (https://skillmd.com/u/sordi-ai)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/sordi-ai/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`