Skip to content

Git Hygiene - Pre-flight & Branch Management

Every coding session MUST begin with this pre-flight checklist. Do NOT write any code, create any files, or make any changes until the checklist passes.

Pre-flight checklist

Run these steps in order before starting work.

Step 1 - Sync remote state

git fetch origin

Step 2 - Inspect current branch

git status
git branch -vv

Capture the current branch name. If HEAD is detached, treat it as if you are on main (go to Step 3).

Step 3 - Guard: on main?

If the current branch is main or master:

  • Do NOT commit to main. Ever.
  • Skip to Step 7 to create a new feature branch.

Step 4 - Guard: branch already merged?

Check whether a PR from this branch has already been merged:

gh pr list --state merged --head "$(git branch --show-current)" --json number,title --limit 5

If the result is non-empty (one or more merged PRs exist):

  1. Tell the user: "The branch <name> has already been merged via PR #N. New work should go on a fresh branch so it gets a clean PR."
  2. Skip to Step 7 to create a new branch.
  3. NEVER add new commits to a merged branch.

Step 5 - Guard: open PR with reviews?

gh pr list --state open --head "$(git branch --show-current)" --json number,title,reviewDecision --limit 1

If an open PR exists and reviewDecision is APPROVED or CHANGES_REQUESTED:

  • Warn the user: "Branch <name> has an open PR (#N) that is under review. Adding commits will change code reviewers have already looked at. Do you want to continue on this branch, or start a new one?"
  • Wait for the user's answer before proceeding.

Step 6 - Guard: branch is stale or diverged?

git rev-list --count origin/main..HEAD
git rev-list --count HEAD..origin/main

If the branch is more than 10 commits behind origin/main:

  • Warn the user: "Branch <name> is N commits behind main. Starting a fresh branch will avoid merge conflicts and keep the PR small."
  • Recommend creating a new branch unless the user explicitly wants to continue.

If the branch is more than 15 commits ahead of origin/main:

  • Warn the user: "Branch <name> is N commits ahead of main. This is a large change set. Consider whether the new work belongs in a separate PR."

Step 7 - Create a new branch (when needed)

If any guard above triggered, or if the user is starting new/unrelated work:

  1. Ask the user what they are working on if you don't already know. You need a short description to name the branch.

  2. Derive a branch name from the task description:

  3. Use lowercase, hyphens, max ~50 chars.
  4. Prefix with feature/, fix/, docs/, or internal/ depending on the nature of the work.

  5. Examples: fix/sync-heartbeat-null-check, feature/add-org-billing, docs/update-readme-setup.

  6. Create the branch from the latest origin/main:

git checkout -b <branch-name> origin/main
  1. Confirm to the user: "Created branch <branch-name> from the latest main. Ready to start."

Mid-session checks

Before each commit

Before running git add / git commit, verify:

git branch --show-current

If you are on main, STOP - you have drifted onto the wrong branch. Stash or move changes to the correct feature branch.

When the user pivots to unrelated work

If the user asks for work that is clearly unrelated to the current branch's purpose (different feature, different bug, different area of the codebase):

  1. Commit or stash any in-progress changes on the current branch.
  2. Run the pre-flight checklist from the top for the new task.
  3. Create a new branch for the new work - do NOT pile unrelated changes onto the current branch.

Tell the user: "That looks like separate work. I'll commit what we have on <current-branch> and start a fresh branch for the new task."

Pushing and PR creation

When the work is ready to push, ask the user if before doing so. Sometimes they may prefer to do the push. There may be a passphrase required. To do the push:

git push -u origin "$(git branch --show-current)"

Then create a PR:

gh pr create --title "<concise title>" --body "$(cat <<'PREOF'
## Summary
<1-3 bullet points describing the changes>

## Test plan
<checklist of what to verify>

PREOF
)"

Quick reference - what to do when...

Situation Action
On main Create new branch from origin/main
Branch was already merged Create new branch from origin/main
Branch has open reviewed PR Ask user before adding commits
Branch is >10 commits behind main Suggest new branch
Branch is >15 commits ahead Suggest splitting work
User asks for unrelated work Commit current work, new branch
gh CLI not available Fall back to git log --oneline origin/main..HEAD for ahead count and warn user to install gh

Troubleshooting

Error: gh: command not found Cause: GitHub CLI is not installed. Solution: The merged-PR and open-PR checks require gh. Install it: sudo apt install gh (Ubuntu/WSL) or brew install gh (macOS). Then authenticate: gh auth login. If gh is unavailable and cannot be installed, skip Steps 4 and 5 but still enforce Steps 3, 6, and 7.

Error: User insists on continuing on a merged branch. Cause: They don't understand why it matters. Solution: Explain briefly: "When a branch is merged, GitHub closes its PR. New commits on the same branch require re-opening or a new PR, and the diff will include all the old already-merged changes, making review confusing. A fresh branch gives you a clean, reviewable PR." Then create the new branch.

Error: User wants to "just push to main." Cause: They want to skip the PR process. Solution: Do not push to main. Explain: "Pushing directly to main skips code review and can break the deployment pipeline. I'll create a branch and PR instead - it only takes a few seconds."