git-branch-naming

name	git-branch-naming
description	Name or repair development branches with semantic prefixes, `<type>/<username>/<short-description>` structure, and migration guidance when work has already started on the wrong branch.

Purpose

Choose or repair development branch names so the branch tells the same semantic story as the work.

Trigger / When to use

Use this skill when:

• the user asks for a branch name
• the agent detects git checkout -b or git switch -c intent
• a task has just been confirmed and the agent should suggest a branch before work starts
• the current branch is clearly misnamed and the user needs a safe migration path

Do not use this skill when:

• the main task is drafting commit messages or deciding release/tagging policy
• the branch is a release or hotfix branch whose lifecycle should be governed by git-release-management
• the user only wants generic Git tutorials unrelated to branch naming

Inputs

• the task's business intent
• the chosen development type such as feat, fix, refactor, docs, or chore
• the username or approved namespace token
• the current branch, including whether work or commits already exist there
• any existing branch names that might conflict
• the expected commit scope or dominant module

Process

1. Decide whether the branch is a normal development branch or a release/hotfix case. Hand release/hotfix timing decisions to git-release-management.
2. Choose a semantic branch type that aligns with the same type system used by git-commit-convention.
3. Build the preferred development branch as <type>/<username>/<short-description>.
4. Keep short-description short, semantic, and lowercase; prefer about 2-4 words in kebab-case that match the dominant scope or business goal.
5. If the repo does not use personal usernames in branch names, stop and ask for the approved namespace token instead of inventing one.
6. If the current branch is wrong but the work has already started, provide an escape path: rename in place, create a new branch from the current state, or otherwise move the work with the least semantic damage.
7. If the description is too broad or crosses multiple semantic areas, recommend splitting into smaller branches or replacing the description with a more abstract but still truthful label.
8. If the preferred branch name already exists, check whether it is really the same task. If not, suggest a more precise suffix or a clear alternate description.
9. Output the recommended branch name plus the repair or creation command, but do not rename branches automatically.

Examples

• Positive: Suggest feat/andrew/auth-session-timeout for a new authentication rule, or repair work on main with git checkout -b feat/andrew/auth-session-timeout.
• Negative: Approve misc/update-stuff, keep coding on main without a migration path, or let a fix/... branch carry a clearly feature-sized workflow change.

Outputs

• one recommended branch name or a small set of tightly related alternatives
• repair commands such as git checkout -b ... or git branch -m ...
• split advice when one task name tries to cover multiple semantic boundaries

Boundaries

• Do not draft commit bodies, PR gates, release tags, or version policy.
• Do not manage release/hotfix approval timing; hand that to git-release-management.
• Do not silently accept a vague or misleading branch name when a clearer semantic name is available.
• Do not auto-run branch creation or rename commands.

Local references

• examples.md: branch naming scenarios, migration commands, conflict handling, and anti-patterns
• references/naming-patterns.md: preferred branch structure, type alignment, and short-description rules
• references/migration-playbooks.md: wrong-branch rescue paths and rename versus recreate guidance
• references/conflict-and-fallbacks.md: name-conflict handling, namespace fallback, and broad-task compression rules