Branch Workflow

Core Question

What branch action is safe given the current working tree, tracking configuration, upstream state, divergence, operation state, and requested blast radius?

When To Use

Use this skill when the user asks to:

• inspect branch state,
• create or switch branches,
• sync with upstream,
• fetch remote state,
• set upstream tracking,
• prepare a branch for PR,
• push a branch after explicit request,
• evaluate force-push or remote branch deletion risk.

When Not To Use

Do not use this skill to resolve file conflicts, recover discarded work, create commits, version a release, or create tags.

Route to:

• resolve-conflicts when unmerged paths or conflict markers exist.
• undo-recover for reset, restore, abort, reflog, clean, force-push recovery, or destructive recovery.
• atomic-commits when organizing staged changes into commits.
• tag-release for Git release tags.
• version-bump, release-notes, or changelog-maintenance for release artifacts.

Required Evidence

Before mutation, inspect or establish:

• git status --short --branch,
• current branch name,
• branch tracking with git branch -vv,
• remote names and URLs when remote action is requested,
• upstream ref when configured,
• ahead/behind counts when upstream exists,
• operation state such as merge, rebase, cherry-pick, or revert in progress,
• default branch from repository evidence, never assumption,
• local and remote SHAs before R4/R5 actions.

Operating Contract

You MAY:

• inspect branch, status, log, upstream, and remote state,
• create or switch local branches when requested and safe,
• fetch remote state when the user requested remote state refresh,
• sync a clean branch when the strategy is explicit or low-risk,
• set upstream, push, force-update, or delete remote refs only under explicit gated workflows.

You MUST:

• inspect state before branch mutation,
• preserve local work and staged state,
• distinguish fetch, pull, merge, rebase, push, and force update,
• explain merge versus rebase choices for diverged branches,
• require exact confirmation for R4/R5 actions,
• verify branch/ref state after mutation.

You MUST NOT:

• pull, merge, or rebase blindly on a dirty or diverged branch,
• set upstream or push silently,
• assume the default branch name,
• resolve conflicts in this skill,
• use bare force-push,
• run destructive cleanup, reset, or branch deletion without explicit confirmation and recovery context.

State / Risk Table

Workflow

1. Identify requested branch action and whether it is read-only, local, or remote/shared.
2. Inspect status, branch, upstream, divergence, remotes, and operation state.
3. Classify state and risk.
4. Separate safe read/local actions from gated remote/destructive actions.
5. Present options for dirty, missing-upstream, detached, diverged, or operation-in-progress states.
6. Execute only explicitly requested and allowed actions.
7. Verify resulting branch/ref/status.
8. Report evidence, action, confirmation, verification, and remaining risk.

Decision Rules

• git fetch is a remote-read/local-ref refresh. It requires explicit user intent for remote state refresh and must be reported as updating remote-tracking refs. It is not equivalent to push, reset, clean, or force-push.
• A dirty tree blocks branch switch or sync when files may be overwritten or when the requested scope is unclear.
• Missing upstream is not permission to run push -u; ask before creating remote tracking.
• Behind-only branches may fast-forward when user requested sync and policy allows it.
• Diverged branches require an explicit merge/rebase choice.
• Rebase on a shared branch is high-risk and requires confirmation.
• Push, upstream creation, remote deletion, and force update are remote/shared mutation.
• Force update must use lease semantics when permitted; bare force update is forbidden.

Workflow Guardrails

Force Push / Shared History Rewrite

Trigger:

• The user asks to force-push, publish rewritten local history, overwrite a remote branch, or update a shared ref after rebase, amend, reset, filter rewrite, or other local rewrite.

Default: <!-- guardrail:branch-force-push.local-rewrite-not-remote-rewrite -->

• Stop normal branch workflow and classify this as R5 shared-ref mutation; local history rewrite does not imply remote rewrite.

Must:

• Inspect git status --short --branch, git branch -vv, remote names, upstream ref, local SHA, current remote SHA, ahead/behind, and whether the branch is shared or protected by repository policy.

<!-- guardrail:branch-force-push.prefer-explicit-lease -->

• Prefer git push --force-with-lease=<ref>:<expected-old-sha> <remote> <local-sha>:<ref> over bare git push --force-with-lease or git push --force when an exact force update is confirmed.
• State the remote/ref blast radius and recovery plan before asking for confirmation.

Must not: <!-- guardrail:branch-force-push.no-implicit-force-push -->

• Treat a successful local rebase, amend, reset, or filter rewrite as permission to force-update a remote branch.
• Use git push --force unless the user explicitly requests bare force and accepts the additional risk after --force-with-lease is explained.

Requires explicit confirmation: <!-- guardrail:branch-force-push.exact-ref-sha-refspec -->

• Remote name, branch/ref, local SHA, remote SHA, expected old remote SHA, intended refspec, intended force update, and recovery or rollback plan.

Verification:

• Verify the remote ref after the confirmed force update.
• Report residual shared-history risk and any unverified external copies, protected-branch policy, or collaborator impact.

Tool Rules

Allowed:

• read-only commands for status, branch, log, upstream, and remote inspection,
• local branch creation or switch when requested and safe,
• fetch when remote-state refresh is explicitly requested,
• narrow sync commands after state and strategy are explicit.

Requires explicit confirmation:

• stash, reset, branch deletion, push, upstream creation, rebase, force update, remote branch deletion.

Forbidden:

• conflict resolution,
• destructive cleanup,
• blind pull/rebase,
• bare force-push,
• remote mutation without exact confirmation.

Verification

Minimum verification:

• R0: inspected evidence summarized.
• R2: branch and status after local mutation.
• R3: status plus recovery/residual-risk note.
• R4: remote/upstream/ref verification after shared mutation.
• R5: exact preflight evidence, explicit confirmation, rescue/rollback plan where possible, and remote ref verification.

For force-push or remote branch deletion, explicit confirmation must name:

• remote name,
• branch/ref name,
• current local SHA,
• current remote SHA when available,
• intended operation,
• recovery or rollback plan.

Use force-with-lease semantics, never bare force update, when force update is explicitly confirmed and allowed.

Output Contract

Final response should include:

## State

- Branch, upstream, divergence, dirty/conflict state.

## Action

- Action taken or proposed.

## Risk / Confirmation

- Risk classification and confirmation status.

## Verification

- Status, branch, upstream, or remote ref checks.

## Remaining Risk

- Unverified CI, local work, or remote-state caveats.

Stop / Confirmation Rules

Stop when the repository state is dirty, conflicted, diverged, missing required evidence, or ambiguous in a way that could overwrite user work, invalidate the requested scope, or require a gated action.

Requires exact confirmation for:

• remote/shared mutation,
• upstream creation through push,
• branch deletion,
• rebase or history rewrite,
• force update,
• destructive local mutation.

Lazy-load References

Load:

• references/branch-states.md for detached, dirty, missing-upstream, or diverged state.
• references/commands.md when command choice is needed.
• references/sync-strategies.md for merge/rebase/fast-forward choices.
• references/failure-modes.md for risky or ambiguous state.
• references/verification.md for R4/R5 verification detail.