branch-name

name	branch-name
description	Generate Git branch names from current branch changes against a base branch. Use this skill whenever the user mentions branch naming, wants to create/rename a branch based on their work, asks for branch name suggestions, or says things like '给这个分支起个名字', '生成分支名', '根据改动起一个 branch 名', 'suggest branch name from diff', 'name this branch based on changes', 'what should I call this branch', or 'name this feature branch'. Also trigger when you see diff-based naming requests or when the user has uncommitted work and asks about branching.
metadata	{"author":"QuentinHsu","version":"2026.03.07"}

Branch Name

Generate clean, team-friendly Git branch names based on current code changes.

Context Reuse (Step 0)

See _shared/context-reuse.md for the context reuse protocol.

If DIFF_CONTEXT or RAW_DIFF is already provided, use it directly to save time and tokens.

Gather Change Context (Step 1)

See _shared/branch-diff-gathering.md for branch diff collection details.

Use branch-level diff as primary source (compare current branch against base branch). This gives you the full picture of what's changing.

Optionally read commit history to improve intent inference across multiple commits.

Infer Intent and Type (Step 2)

See _shared/type-classification.md for the detailed classification rules.

Determine primary intent from changes:

• feature (new capability)
• bugfix (defect fix)
• performance (same capability, better experience / UI / interaction)
• refactor (internal restructuring)
• docs (documentation)
• chore (maintenance/tooling)
• test (tests only)

Use the dominant user-facing outcome:

• choose feature only when the branch adds a net-new capability or workflow
• choose performance when the branch mainly improves speed, smoothness, clarity, UI polish, or interaction flow without changing actual utility
• for UI-only or UX-only improvements, prefer performance over feature
• if behavior was broken and is now corrected, prefer bugfix

Extract 2-5 keywords from modified modules, entities, or behavior. These keywords will form the branch name slug.

Build Naming Candidates (Step 3)

Use slash style prefix by default: <prefix>/<slug>

Prefix mapping:

• feature → feat
• bugfix → fix
• performance → perf
• refactor → refactor
• docs → docs
• chore → chore
• test → test

Slug guidelines:

• lowercase only (easier to type, avoids case-sensitivity issues)
• words separated by - (standard Git convention)
• keep 2-6 words when possible (balance between clarity and brevity)
• avoid vague words like update, misc, changes (not descriptive)
• avoid issue IDs unless user requests them (IDs are better in commits/PRs)

Why these guidelines:

• Lowercase avoids confusion on case-sensitive filesystems
• Hyphens are the Git community standard (not underscores or camelCase)
• Descriptive slugs help teammates understand branches at a glance
• Short names are easier to type and fit better in Git UIs

Validate and Rank (Step 4)

Output 3 candidates by default, ordered from best to acceptable.

Validation:

• ≤ 48 characters preferred (hard max 63 due to filesystem limits)
• no spaces, no underscores, no trailing slash
• reflects actual diff intent

If intent is ambiguous, include one neutral fallback like chore/<area>-cleanup.

Output Format (Step 5)

Branch names are always English tokens — output English only (no bilingual output needed).

Output structure:

• Recommended label above the best branch name
• Alternative 1 and Alternative 2 labels above the two additional candidates
• optional one-line rationale per candidate
• Wrap each branch name candidate in its own text code block for direct copying
• Output exactly three branch name code blocks by default
• Keep labels outside code blocks so copying a block copies only the branch name

Example Output

Recommended

fix/auth-token-refresh-race

Alternative 1

fix/auth-refresh-lock

Alternative 2

refactor/auth-token-renewal-flow

Conventions

• Do not fabricate intent beyond actual changes
• Prefer domain terms already present in file paths/symbol names (maintains consistency with codebase)
• Keep names readable for both humans and CI tooling