Branch Finishing and PR Preparation

Iron Law

NEVER MERGE WITHOUT ALL CHECKS PASSING

Steps

1. Verify

• 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

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

• 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

• 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

• 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

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:

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