Branch Finishing and PR Preparation
Iron Law
NEVER MERGE WITHOUT ALL CHECKS PASSING
Steps
1. Verify
Confirm the branch is ready for review.
- Run the full test suite — all tests must pass
- Run typecheck and lint — zero errors
- Verify all acceptance criteria from the story/PRD are met
- Check for leftover debug code, TODOs, or commented-out blocks
- Ensure no untracked files that should be committed
2. Rebase
Bring the branch up to date with the target branch.
git fetch origin
git rebase origin/main- Resolve any conflicts carefully — do not blindly accept incoming or current
- After rebase, re-run all quality checks (tests, typecheck, lint)
- If rebase conflicts are extensive, consider whether the branch diverged too far
3. Clean History
Ensure commits tell a clear story.
- Each commit should be atomic — one logical change per commit
- Commit messages should explain WHY, not just WHAT
- Squash fixup commits (typo fixes, lint fixes) into their parent commit
- Reorder commits so dependencies come before dependents
- Every commit in the history should pass quality checks independently
4. Write PR Description
Create a clear, reviewable pull request description.
- Title: Concise summary of what the PR does (under 72 characters)
- Summary: 2-3 sentences explaining the change and its motivation
- Changes: Bulleted list of what was added, modified, or removed
- Testing: How the changes were tested, what to verify
- Screenshots: If UI changes, include before/after
- Related issues: Link to the story, issue, or PRD that motivated this work
5. Self-Review
Review your own diff before requesting review from others.
- Read every changed line as if someone else wrote it
- Check for security issues (hardcoded secrets, injection vectors)
- Check for performance issues (N+1 queries, unbounded loops)
- Verify error handling is adequate
- Confirm naming is clear and consistent
6. Push and Create PR
Push the branch and open the pull request.
git push origin <branch-name>
gh pr create --title "<title>" --body "<description>"- Set appropriate reviewers
- Add relevant labels
- Link to the related issue or story
- Do not merge your own PR unless explicitly permitted
Red Flags — If You Catch Yourself Thinking:
| Thought | Reality |
|---|---|
| "Tests mostly pass, one flaky test is fine" | ALL tests must pass. Fix the flaky test or skip it with documentation. |
| "The commit history is messy but the code is right" | Messy history makes review harder and bisect useless. Clean it up. |
| "I'll write the PR description later" | The PR description IS the review guide. Write it now while context is fresh. |
| "This is a small change, no need for self-review" | Small changes cause big bugs. Review every line. |
Rules
- All quality checks must pass before pushing
- Every commit must be atomic and independently valid
- PR description is required — never create a PR without one
- Self-review before requesting external review
- Never force-push to a shared branch without coordinating with collaborators