branch-sync-gate

Wrong skill? Starting a brand-new branch → using-git-worktrees. About to commit → unified-commit-gate. Branch work is done → finishing-a-development-branch.

Branch Sync Gate

The Rule

Before touching any existing shared branch — pull first.

This is not optional. It is not skippable. It applies even if you were just working on the branch 5 minutes ago.

When to Use

Any time you are about to:

• Resume or continue work on a branch that exists on a remote
• Run tests on an existing branch
• Write code on an existing branch
• Review a PR branch locally
• Add commits to a branch shared with other developers

The Gate (Run This First — Before Anything Else)

# Step 1: Where are we?
git branch --show-current
git remote -v

# Step 2: Fetch and check for remote changes
git fetch origin
git log HEAD..origin/$(git branch --show-current) --oneline 2>/dev/null

Remote has commits not in local?	Action
Yes	git pull --rebase origin $(git branch --show-current) — then verify
No	Proceed — you are in sync
Unsure	Fetch and check. Never assume.

# Step 3: Pull if behind
git pull --rebase origin $(git branch --show-current)

# Step 4: Confirm baseline
git log --oneline -5
git status

Non-Negotiable

Do not start work, run tests, or write a single line of code until this gate passes.

If you find yourself already mid-work and realize you haven't pulled — stop, pull, verify the state hasn't changed under you, then continue.

Why This Exists

Incident 2026-04-23: Agent began writing tests on an active PR branch without pulling first. A teammate had pushed two commits in the interim. The agent iterated tests against stale code, created a merge conflict on push, resolved it by discarding its own changes, then pushed a broken build (failing assertion + TypeScript error). Required multiple extra fix commits on a PR that was otherwise ready to merge.

Root cause: No skill enforced sync at session start. Every existing gate (sp-commit, sp-finish, pre-commit-gate) fires at commit time or later — zero enforcement at the moment work begins.

Anti-Patterns

Wrong	Right
Assume local is up to date because you just worked on it	git fetch and check
Pull after writing code	Pull before writing code
Merge conflicts on push	Prevented by pulling first
Re-fixing what a teammate already fixed	Prevented by pulling first

Failure Modes

Symptom	Fix
git fetch hangs	Check network / VPN; run git remote -v to verify remote URL
Merge conflict after pull	git status to identify conflicts; resolve, then git rebase --continue
Branch doesn't exist on remote	Verify with git branch -r; may be a new local-only branch
Remote HEAD diverged too far	Consider git fetch origin && git log --oneline origin/branch before rebasing

Companion Skills

• git-branch-conventions: Use when creating a brand-new branch
• unified-commit-gate: Fires at commit time (this fires at session start)
• finishing-a-development-branch: Fires when branch work is complete