---
description: Create or validate a feature branch with an intent-based name
argument-hint: [description of what you're working on]
---

# Branch Command

Create or validate a feature branch with an auto-generated name based on intent. Operates in two modes depending on current branch.

---

## Check Current Branch

Run `git rev-parse --abbrev-ref HEAD 2>/dev/null` to get the current branch.

**If on `main` or `master`:**
- Proceed to **Create Mode**.

**If already on a feature branch:**
- Proceed to **Validate Mode**.

---

## Create Mode (from main/master)

### Determine Intent

**If argument is provided ($ARGUMENTS is not empty):**
- Use it as the intent description for the branch name.

**If no argument provided ($ARGUMENTS is empty):**
- Ask the user: "Short description for the branch name?"
- Wait for user response.

### Generate Branch Name

Infer the branch type prefix from keywords in the description (see `~/.claude/skills/_shared/branch-naming.md`). If no keywords match, default to `feat/`.

Follow the slug generation and collision check algorithm in `~/.claude/skills/_shared/branch-naming.md`.

### Create Branch

1. Run `git pull --ff-only` to ensure local `main` is up to date before branching. If it fails (e.g., diverged from origin), warn the user and ask whether to proceed anyway.
2. Run `git checkout -b <type>/<slug>`.
3. Confirm: "Created and switched to branch `<type>/<slug>`."

---

## Validate Mode (from feature branch)

When already on a feature branch, validate that the branch name matches the actual changes.

### Infer Intent from Changes

Determine what the changes are actually about by examining (in priority order):

1. **Uncommitted changes** — Run `git diff` and `git diff --cached` to see unstaged and staged changes
2. **Branch commits** — Run `git log --oneline main..HEAD` and `git diff main...HEAD` to see all changes on this branch vs main
3. **Conversation context** — Consider what the user has been working on in this session (fallback)

From the combined changes, determine:
- **What changed**: which files, what kind of modifications (new feature, bug fix, refactor, docs)
- **Intent summary**: a short phrase describing the purpose of the changes (e.g., "add time budget to design skill research")

### Compare to Current Branch Name

Using the same prefix-inference and slug-generation logic from Create Mode, determine what the branch **should** be named based on the inferred intent.

**If the current branch name is appropriate** (prefix type matches and slug reasonably describes the changes):
- Confirm: "Branch `<branch-name>` matches the changes — OK."
- Return success. No further action needed.

**If the current branch name is mismatched** (wrong prefix type or slug describes something different):
- Inform the user: "Branch `<current>` doesn't match the changes (which are about: <intent summary>). Rebranching to `<type>/<slug>`."
- Stash any uncommitted changes: `git stash` (skip if working tree is clean)
- Create and switch to the new branch from current HEAD: `git checkout -b <type>/<slug>`
- Pop stash if one was created: `git stash pop`
- Confirm: "Rebranched to `<type>/<slug>` — all changes preserved."

---

## Example Usage

```
/branch                              # Asks for description, infers type, creates branch (from main)
/branch add user authentication      # Creates feat/add-user-authentication (from main)
/branch fix login timeout bug        # Creates fix/login-timeout-bug (from main)
/branch                              # Validates branch matches changes, auto-rebranches if mismatched (from feature branch)
```