branch-naming

# Branch Naming Skill

Generate and validate Git branch names from conventional commit messages or plain descriptions. This skill only handles naming -- it does not create, delete, or manage branches.

## Instructions

### Step 1: Parse Input

Determine the commit type and subject from whatever the user provides.

**If a conventional commit message** (e.g., `feat: add user auth`):
- Extract type, optional scope, and subject
- Pattern: `<type>[optional scope]: <description>`

**If a plain description** (e.g., `add user authentication`):
- Infer type from keywords (see `references/type-mapping.md` for full mapping)
- Keywords: add/implement/create -> feat, fix/resolve/correct -> fix, document/readme -> docs, refactor/restructure -> refactor, test/spec -> test, remove/delete/update -> chore
- Default to `feat` when no keywords match

Strip banned characters (emojis, special chars) from the input. If the input is too vague to determine a type (e.g., "stuff", "things"), prompt the user for a more descriptive input starting with an action verb.

**Gate**: Commit type identified and subject extracted. If not, prompt for clarification before continuing.

### Step 2: Generate Branch Name

**Map type to prefix** using the standard table (or `.branch-naming.json` overrides if present in the repo root):

| Type | Prefix |
|------|--------|
| feat | feature/ |
| fix | fix/ |
| docs | docs/ |
| refactor | refactor/ |
| test | test/ |
| chore | chore/ |
| style | style/ |
| perf | perf/ |
| build | build/ |
| ci | ci/ |
| revert | revert/ |

Every branch name must have a prefix from this list -- unprefixed names like `add-user-authentication` break CI/CD automation and make filtering impossible.

**Sanitize the subject to kebab-case** using the 7-step pipeline (see `references/sanitization-rules.md`):
1. Lowercase
2. Strip leading/trailing whitespace
3. Replace spaces with hyphens
4. Replace underscores with hyphens (underscores violate kebab-case convention and create inconsistency with conventional commits)
5. Remove special characters (keep only a-z, 0-9, hyphens)
6. Collapse multiple consecutive hyphens
7. Remove leading/trailing hyphens

Only a-z, 0-9, and hyphens are allowed in the subject. The forward slash appears only once, separating prefix from subject.

**Apply the 50-character length limit** (prefix + subject combined). If exceeded:
1. Remove filler words (the, a, with, and, for, etc.)
2. Apply common abbreviations (authentication -> auth, configuration -> config)
3. Truncate at word boundaries -- never cut mid-word

Long names signal scope creep; move detail to the commit message body rather than cramming it into the branch name.

**Combine prefix + sanitized subject**:

Example: `feat: add user authentication` -> `feature/add-user-authentication`

**Gate**: Generated name has a valid prefix, uses kebab-case, stays within the length limit, and contains only allowed characters.

### Step 3: Validate

Run all checks against the generated (or user-provided) name:

**Format validation**:
- Has a valid prefix from the allowed list
- Subject is kebab-case (no uppercase, no underscores)
- Only allowed characters (a-z, 0-9, hyphens, one forward slash)
- No leading/trailing hyphens in subject
- No consecutive hyphens
- Name is specific enough to convey purpose (`feature/updates` or `fix/stuff` are too vague)

**Length check**: Total length is 50 characters or fewer.

**Duplicate detection**:

```bash
# Check local
git branch --list "<branch-name>"

# Check remote
git ls-remote --heads origin "<branch-name>"
```

If a duplicate is found, generate alternatives:
1. Append `-v2`, `-v3` for versioning
2. Append date `-YYYYMMDD` for uniqueness
3. Ask user for a custom suffix

**Repository convention compliance**: Check `.branch-naming.json` if present for custom prefix restrictions.

**Gate**: All validation checks pass. If any fail, regenerate with adjustments or present alternatives.

### Step 4: Confirm

Present the validated name and wait for user approval before proceeding:

```
Generated Branch Name: feature/add-user-authentication
  Type: feat (feature)
  Length: 31 characters
  Format: Valid
  Duplicates: None found

Use this branch name? [Y/n]
```

Handle the response:
- **Yes**: Output the final name with a `git checkout -b` command
- **No**: Return to Step 1 with new input
- **Customize**: User provides a custom name; run it through Step 3 validation

Skip confirmation only in automated/scripted workflows where the caller has explicitly opted into auto-accept.

**Gate**: User approved name. Workflow complete.

### Examples

**From a conventional commit**:
Input: `feat: add user authentication`
1. Parse: type=feat, subject="add user authentication"
2. Map feat -> feature/, sanitize -> "add-user-authentication"
3. Validate format, length (31 chars), no duplicates
4. Present and confirm
Result: `feature/add-user-authentication`

**From a plain description with truncation**:
Input: `add comprehensive user authentication system with OAuth2 and JWT`
1. Infer type=feat from "add" keyword
2. Sanitize, remove fillers, abbreviate auth -> 32 chars
3. Validate all checks pass
4. Present and confirm
Result: `feature/add-user-auth-oauth2-jwt`

**Validating an existing branch name**:
Input: `feature/User_Authentication`
1. Detect uppercase letters and underscores
2. Report issues with corrections
Result: Suggest `feature/user-authentication`

---

## Error Handling

### Error: "Cannot Infer Commit Type"
Cause: Description too vague (e.g., "stuff", "things") to determine type
Solution:
1. Prompt user to start with action verb (add, fix, update, remove)
2. Suggest using `--type` flag to specify explicitly
3. Provide examples of descriptive input

### Error: "Name Exceeds Length Limit"
Cause: Description too long even after truncation
Solution:
1. Remove filler words and apply abbreviations
2. Suggest shorter focused description
3. Move detail to commit message body instead of branch name

### Error: "Duplicate Branch Detected"
Cause: Branch name already exists locally or remotely
Solution:
1. Suggest alternatives with -v2 or date suffix
2. Offer to check out existing branch instead
3. Prompt for custom differentiating suffix

---

## References

- `${CLAUDE_SKILL_DIR}/references/type-mapping.md`: Conventional commit type to branch prefix mapping
- `${CLAUDE_SKILL_DIR}/references/naming-conventions.md`: Branch format rules, character whitelist, examples
- `${CLAUDE_SKILL_DIR}/references/sanitization-rules.md`: 7-step text sanitization pipeline and truncation strategies
- `${CLAUDE_SKILL_DIR}/references/examples.md`: Good/bad examples with corrections and integration patterns