krzysztofsurdy/finishing-branch

Finishing a Development Branch

The code is written. Tests are green locally. Now what? The gap between "done coding" and "merged to main" is where branches rot, conflicts accumulate, and mistakes happen. This playbook is the systematic bridge: verify, review, integrate, clean up. Every time, in order, nothing skipped.

Never push without green. Never merge without review evidence.

When to Use

• Implementation is complete and you are ready to integrate
• You need to decide between merge, squash, rebase, or PR
• A branch has been sitting and needs to be wrapped up
• You are finishing work in a worktree and need to clean up
• You are managing stacked branches and need to land them in order

Quick Start

# Verify everything passes
git diff --stat main...HEAD
make test && make lint && make typecheck

# Push and open a PR (adjust target as needed)
git push -u origin HEAD
gh pr create --fill

If you need more control, follow the phases below.

---

Phase 1: Working-Tree Sanity

Before anything else, ensure the working tree is in a known-good state.

# Check for uncommitted changes
git status

# Check for forgotten stashes
git stash list

# Ensure you are on the right branch
git branch --show-current

# Verify upstream tracking is set
git rev-parse --abbrev-ref --symbolic-full-name @{u}

| Check | Pass Condition | Fix | |---|---|---| | No uncommitted changes | git status shows clean tree | Commit or stash intentionally | | No orphaned stashes | git stash list is empty or all stashes are accounted for | Apply or drop stale stashes | | Correct branch | Branch name matches your work | git checkout <branch> | | Upstream set | Tracking branch exists | git push -u origin HEAD on first push | | No untracked noise | No generated files, build artifacts, or editor files | Add to .gitignore or remove |

---

Phase 2: Pre-Push Verification

Run the full verification suite before pushing. Order matters - fail fast on the cheapest checks first.

# 1. Lint (fastest, catches formatting/style issues)
make lint            # or: npm run lint, cargo clippy, flake8, etc.

# 2. Type checking (catches type errors without running code)
make typecheck       # or: npx tsc --noEmit, mypy, phpstan, etc.

# 3. Unit tests (fast feedback on logic correctness)
make test            # or: npm test, pytest, phpunit, cargo test, etc.

# 4. Integration / end-to-end tests (slower, catches wiring issues)
make test-integration

# 5. Build (ensures the artifact compiles / bundles cleanly)
make build           # or: npm run build, cargo build --release, etc.

If any step fails, stop and fix before proceeding. Do not push broken code.

See Pre-Push Checks Reference for the full verification order, CI parity tips, and conflict detection.

---

Phase 3: Diff Review

Self-review the full diff before handing it to others. You will catch things automated tools miss.

# Full diff against the target branch
git diff main...HEAD

# Commit-by-commit review (more granular)
git log --oneline main..HEAD
git show <commit-hash>

# Stat summary (spot unexpectedly large changes)
git diff --stat main...HEAD

# Check for secrets or sensitive data
git diff main...HEAD | grep -iE '(password|secret|token|api.key|private.key)' || true

Self-Review Checklist

• [ ] No debug code left behind (console.log, dd(), print_r, var_dump, TODO)
• [ ] No commented-out code that should be deleted
• [ ] No secrets, tokens, or credentials in the diff
• [ ] No unrelated changes mixed into the branch
• [ ] Commit messages are clear and follow project conventions
• [ ] New files are in the correct directories
• [ ] Tests cover the changes (not just existing tests passing)

---

Phase 4: Integration Strategy Selection

Choose how to integrate based on your team's workflow, the branch's history, and the target branch.

| Strategy | When to Use | Command | |---|---|---| | Pull Request | Team requires review, CI gates, or audit trail | Push + open PR (see Phase 6) | | Direct merge | Trunk-based, solo project, or pre-approved change | git checkout main && git merge --no-ff <branch> | | Squash and merge | Branch has messy intermediate commits | Via PR settings, or: git merge --squash <branch> | | Rebase and merge | Linear history desired, clean commit discipline | git rebase main && git checkout main && git merge --ff-only <branch> | | Stacked PR | Branch builds on another unmerged branch | Push + open PR targeting parent branch |

See Integration Strategies Reference for the full decision matrix, rebase vs merge trade-offs, and stacked PR workflow.

---

Phase 5: Message Writing

Write a clear, structured message whether you are creating a PR or a merge commit.

PR Message Structure

## Summary
What changed and why (1-3 sentences).

## Changes
- Bullet list of specific changes

## Test Plan
- How to verify the changes work

## Risks
- What could go wrong, migration notes, rollback considerations

## Linked Tickets
- PROJ-123

For comprehensive PR messages, use the pr-message-writer skill which provides templates, structured sections, and verification queries.

See PR Message Template Reference for the full template and guidance on writing effective messages.

---

Phase 6: Push and PR Creation

Push to Remote

# First push (sets upstream tracking)
git push -u origin HEAD

# Subsequent pushes
git push

# After rebase (use --force-with-lease, never --force)
git push --force-with-lease

Open a Pull Request

GitHub:

# Basic PR
gh pr create --title "feat: add user email verification" --body-file pr-description.md

# PR targeting a specific branch (for stacked PRs)
gh pr create --base feat/parent-branch --title "feat: add verification UI"

# Draft PR (not ready for review yet)
gh pr create --draft --fill

GitLab:

glab mr create --title "feat: add user email verification" --description-file pr-description.md

# Target a specific branch
glab mr create --target-branch feat/parent-branch

# Draft MR
glab mr create --draft

Bitbucket:

# Using Bitbucket's REST API via curl
curl -X POST -H "Content-Type: application/json" \
  "https://api.bitbucket.org/2.0/repositories/{workspace}/{repo}/pullrequests" \
  -d '{"title": "feat: add email verification", "source": {"branch": {"name": "feat/email-verification"}}, "destination": {"branch": {"name": "main"}}}'

Direct Merge (No PR)

# Fetch latest and merge with a merge commit
git checkout main
git pull
git merge --no-ff feat/my-branch -m "Merge feat/my-branch: add user email verification"

# Push main
git push

---

Phase 7: Cleanup

After the branch is merged, clean up local and remote references.

# Delete the local branch
git branch -d feat/my-branch

# Delete the remote branch (if not auto-deleted by PR merge)
git push origin --delete feat/my-branch

# Prune remote tracking references
git fetch --prune

# If working in a worktree, remove it
git worktree remove /path/to/worktree

See Cleanup Commands Reference for pruning stale branches, worktree cleanup, and upstream maintenance.

---

Recovery

Common mistakes and how to fix them.

| Mistake | Recovery | |---|---| | Force-pushed the wrong branch | git reflog to find the pre-push commit, then git push --force-with-lease origin <sha>:<branch> | | Deleted an unmerged branch | git reflog to find the tip, then git checkout -b <branch> <sha> | | Pushed secrets to remote | Rotate the secret immediately, then git filter-repo to purge from history | | Merged to wrong target branch | git revert -m 1 <merge-commit> on the wrong target, then merge to the correct one | | Rebase went wrong mid-way | git rebase --abort to return to pre-rebase state | | Lost work after worktree removal | git reflog - commits survive worktree deletion if they were committed | | PR targets wrong base branch | Update the PR's base branch in the hosting platform UI or CLI |

See Recovery Reference for detailed walkthroughs of each recovery scenario.

---

Quality Checklist

Run through this before considering the branch done.

• [ ] All tests pass (unit, integration, e2e as applicable)
• [ ] Linter and type checker report no errors
• [ ] Build completes without warnings
• [ ] Self-reviewed the full diff - no debug code, secrets, or unrelated changes
• [ ] Commit messages follow project conventions
• [ ] PR description explains what, why, and how to verify
• [ ] Target branch is correct
• [ ] Branch is up to date with the target (rebased or merged)
• [ ] CI pipeline passes on the remote
• [ ] Reviewer(s) assigned (if PR workflow)
• [ ] Local branch and worktree cleaned up after merge

---

Critical Rules

1. Never force-push to main, master, or any shared long-lived branch. Use --force-with-lease on feature branches only.
2. Never skip verification. A single untested push can break the pipeline for the entire team.
3. Never delete an unmerged branch without explicit confirmation. Recover with git reflog if it happens accidentally.
4. Never push secrets. Check the diff before every push. Rotate immediately if it happens.
5. Always use --force-with-lease instead of --force. It prevents overwriting someone else's work on a shared branch.
6. Always clean up after merge. Stale branches and orphaned worktrees accumulate and cause confusion.
7. Always write a meaningful PR/merge message. "Fix stuff" helps nobody - explain what changed and why.
8. Rebase only your own branches. Rebasing shared branches rewrites history others depend on.

---

Reference Files

| Reference | Contents | |---|---| | Pre-Push Checks | Verification command order, CI parity, conflict detection, pre-push hook setup | | Integration Strategies | Merge vs rebase vs squash decision matrix, stacked PRs, when each strategy fits | | PR Message Template | Structured PR template, writing guidance, cross-reference to pr-message-writer skill | | Cleanup Commands | Branch pruning, worktree removal, upstream cleanup, batch operations | | Recovery | Detailed recovery walkthroughs for force-push, deleted branch, lost stash, bad merge |

---

Integration with Other Skills

| Situation | Recommended Skill | |---|---| | Writing a comprehensive PR message | pr-message-writer | | Reviewing code before merging | code-review-excellence | | Managing git worktrees | worktree-start, worktree-list, worktree-switch, worktree-clean | | Choosing a branching strategy | git-workflow | | Running verification before declaring done | verification-before-completion | | Requesting a structured code review | requesting-code-review |