BubbleBuffer/using-git-branches

Using Git Branches

Overview

Create ordinary git branches in the current checkout for isolated feature work.

Core principle: Clean baseline + normal branch = trackable, understandable isolation.

Announce at start: "I'm using the using-git-branches skill to set up an isolated git branch."

Branch Setup

1. Inspect Current State

git branch --show-current
git status --short

If the working tree is dirty, classify the changes before branching:

| Dirty state | Action | |-------------|--------| | User changes related to this feature | Ask whether to carry them onto the new branch | | Unrelated user changes | Stop and ask how to handle them | | Generated or dependency noise | Ask before cleaning or committing | | Clean | Continue |

Never stash, reset, checkout, or delete user changes without explicit approval.

2. Choose Base Branch

Prefer the user's stated base branch. If none was given:

git merge-base HEAD main 2>/dev/null && echo main || echo master

Ask if ambiguous, if the current branch is not main/master, or if the feature depends on unmerged work:

Which branch should this feature start from?
1. Current branch (<current-branch>)
2. main
3. master
4. Other (specify)

3. Create Branch

Use a descriptive branch name such as feature/<name> or fix/<name>:

git switch -c feature/<name>

If already on the correct branch, do not create another one. Report that the branch is already isolated and continue to baseline verification.

4. Verify Clean Baseline

Run the project-appropriate baseline command before producing committed artifacts:

npm test
cargo test
pytest
go test ./...

If dependencies are missing, run the project's normal install command first. Do not run package installs just because a new branch was created.

If tests fail: Report failures and ask whether to investigate or proceed with a known-bad baseline.

If tests pass: Report ready.

5. Report Status

Branch ready: <branch-name>
Base branch: <base-branch>
Working tree: clean
Baseline: <command> passed (<summary>)
Ready to implement <feature-name>

Quick Reference

| Situation | Action | |-----------|--------| | On main/master and clean | git switch -c feature/<name> | | On a prerequisite branch | Ask whether to branch from current branch | | Dirty unrelated changes | Stop and ask | | Already on correct feature branch | Verify baseline, do not create another branch | | Tests fail during baseline | Report failures and ask |

When NOT To Use

• Already on the user-approved branch for this work
• Docs-only or scratch work the user explicitly asked to perform without a branch
• Inside a subagent that inherits the controller's branch context
• When the user has pinned the working branch for the session

In those cases, verify the baseline instead of creating a new branch.

Common Mistakes

Using Anything Other Than Git Branches

• Problem: Extra isolation mechanisms hide branch state and conflict with this workflow.
• Fix: Use normal git branch commands only.

Working On Main/Master

• Problem: Changes mix with shared branch history.
• Fix: Create a feature branch unless the user explicitly approves working on the current branch.

Ignoring Dirty State

• Problem: User changes get mixed into unrelated work or lost.
• Fix: Inspect git status --short and ask before moving, stashing, deleting, or committing existing changes.

Skipping Baseline Tests

• Problem: New failures cannot be distinguished from pre-existing failures.
• Fix: Run a project-appropriate baseline and report failures before proceeding.

Red Flags

Never:

• Use anything other than ordinary git branch commands for this skill
• Start implementation on main/master without explicit user consent
• Modify, stash, reset, or delete dirty user changes without approval
• Proceed with failing baseline tests without asking

Always:

• Use ordinary git branch commands
• Verify the selected branch and working tree state
• Run baseline verification before committed artifacts

Integration

Use after:

• brainstorming — once the design is approved and you are about to commit the spec or any planning artifact

Prerequisite for:

• writing-plans — plans must be authored on the feature branch
• subagent-driven-development — tasks execute on the feature branch
• Any skill that produces committed artifacts

Pairs with:

• finishing-a-development-branch — handles the branch once work is complete