Manage Branch Skill

Purpose

Enforce branch naming conventions and provide safe branch creation/switching operations with proper validation.

CRITICAL POLICY

Branch Naming Convention

ALL branches MUST be prefixed with mriley/

Valid branch name patterns:

• mriley/feat/<descriptive-name>
• mriley/fix/<issue-description>
• mriley/refactor/<component-name>
• mriley/perf/<optimization-description>
• mriley/chore/<task-description>
• mriley/docs/<documentation-update>
• mriley/test/<testing-addition>

Examples of CORRECT names:

• ✅ mriley/feat/user-authentication
• ✅ mriley/fix/parser-null-handling
• ✅ mriley/refactor/api-validation
• ✅ mriley/perf/optimize-query-performance

Examples of INCORRECT names:

• ❌ feat/user-authentication (missing mriley/ prefix)
• ❌ user-authentication (missing prefix and type)
• ❌ fix-bug (missing mriley/ prefix)
• ❌ pedro/feat/something (wrong user prefix)

Workflow

Operation 1: Create New Branch

Step 1.1: Determine Branch Type

Ask user or infer from context:

• feat: New feature
• fix: Bug fix
• refactor: Code restructuring
• perf: Performance improvement
• chore: Maintenance task
• docs: Documentation
• test: Test additions

Step 1.2: Generate Branch Name

Based on work description, generate name:

Format:

mriley/<type>/<short-descriptive-name>

Naming guidelines:

• Use kebab-case (lowercase with hyphens)
• Be descriptive but concise (2-4 words)
• Focus on WHAT, not HOW
• Avoid ticket numbers (unless no description)
• Max 50 characters total

Examples:

mriley/feat/jwt-authentication
mriley/fix/memory-leak-parser
mriley/refactor/split-monolithic-handler
mriley/perf/cache-database-queries

Step 1.3: Validate Branch Name

Check against requirements:

• ✅ Starts with mriley/
• ✅ Has type (feat/fix/refactor/etc)
• ✅ Has descriptive name
• ✅ Uses kebab-case
• ✅ Length ≤ 50 characters

Step 1.4: Check Current Git Status

git status

If uncommitted changes exist:

⚠️ Uncommitted changes detected

You have uncommitted changes in your working directory:
- src/api/handlers.go (modified)
- pkg/auth/validator.go (new file)

Options:
1. Commit changes first (recommended)
2. Stash changes: git stash
3. Discard changes: git restore . (DANGEROUS)

What would you like to do?

STOP and wait for user decision.

Step 1.5: Determine Base Branch

Check which branch to create from:

git branch --show-current

Common scenarios:

• On main/master → Create from current (typical)
• On feature branch → Ask if creating from current or from main
• On develop → Create from current (if using gitflow)

If uncertain, ask user:

Create branch from:
1. Current branch (main)
2. Different branch (specify)

Step 1.6: Create Branch

git checkout -b mriley/<type>/<name>

Or if creating from specific base:

git checkout -b mriley/<type>/<name> origin/main

Step 1.7: Verify Creation

git branch --show-current

Report success:

✅ Branch created successfully

Branch: mriley/feat/jwt-authentication
Base: main
Status: Clean working directory

You can now start working on this branch.

Operation 2: Switch Branch

Step 2.1: Check Current Status

git status

If uncommitted changes:

⚠️ Uncommitted changes detected

Cannot switch branches with uncommitted changes.

Options:
1. Commit changes first (recommended)
2. Stash changes: git stash
3. Discard changes: git restore . (DANGEROUS)

What would you like to do?

STOP and wait for user decision.

Step 2.2: List Available Branches (Optional)

If user unsure which branch to switch to:

git branch -v

Show branches with descriptions:

Available branches:
* main                    a1b2c3d Last commit message
  mriley/feat/auth        d4e5f6g Add JWT validation
  mriley/fix/parser-bug   g7h8i9j Fix null pointer

Step 2.3: Switch Branch

git checkout <branch-name>

Or fetch and checkout remote branch:

git fetch origin
git checkout -b <branch-name> origin/<branch-name>

Step 2.4: Verify Switch

git branch --show-current

Report success:

✅ Switched to branch: mriley/feat/auth

Branch: mriley/feat/auth
Latest commit: d4e5f6g Add JWT validation
Status: Up to date with origin/mriley/feat/auth

Operation 3: Validate Existing Branch Name

If checking/fixing existing branch that doesn't follow convention:

Step 3.1: Get Current Branch

git branch --show-current

Step 3.2: Validate Name

Check if matches mriley/<type>/<name> pattern.

If invalid:

⚠️ Branch name doesn't follow convention

Current: feat/user-authentication
Required: mriley/feat/user-authentication

This branch should be renamed to follow convention.

Options:
1. Rename current branch: git branch -m mriley/feat/user-authentication
2. Create new branch with correct name
3. Continue with current name (NOT recommended)

What would you like to do?

Step 3.3: Rename Branch (If Requested)

# Rename local branch
git branch -m mriley/<type>/<name>

# If already pushed, delete old remote and push new
git push origin --delete <old-name>
git push -u origin mriley/<type>/<name>

Integration with Other Skills

This skill is invoked by:

• create-pr - When creating pull request

This skill may invoke:

• safe-commit - If user wants to commit before switching

Error Handling

Error: Branch already exists

❌ Branch already exists: mriley/feat/auth

Options:
1. Switch to existing branch: git checkout mriley/feat/auth
2. Use different name: mriley/feat/auth-v2
3. Delete existing branch (DANGEROUS - requires confirmation)

What would you like to do?

Error: Invalid branch name

❌ Invalid branch name

Provided: pedro/feat/something
Issue: Must use 'mriley/' prefix, not 'pedro/'

Corrected: mriley/feat/something

Shall I use the corrected name?

Error: Cannot switch (uncommitted changes)

❌ Cannot switch branches

Uncommitted changes in:
- src/api/handlers.go
- pkg/auth/validator.go

Please commit or stash changes first.

Error: Branch doesn't exist

❌ Branch doesn't exist: mriley/feat/nonexistent

Available branches matching 'feat':
- mriley/feat/auth
- mriley/feat/parser

Did you mean one of these?

Best Practices

1. Always validate - Check branch name follows convention
2. Check git status - Ensure clean state before operations
3. Descriptive names - Help future you understand the work
4. Confirm with user - When renaming or making destructive changes
5. Report clearly - Show before/after state
6. Handle errors gracefully - Provide options, not just errors

Branch Naming Examples

Good Examples

Features:

• mriley/feat/oauth-integration
• mriley/feat/real-time-notifications
• mriley/feat/export-to-csv

Bug Fixes:

• mriley/fix/race-condition-handler
• mriley/fix/memory-leak-cache
• mriley/fix/null-pointer-parser

Refactoring:

• mriley/refactor/extract-validation-logic
• mriley/refactor/split-large-service
• mriley/refactor/improve-error-handling

Performance:

• mriley/perf/optimize-database-queries
• mriley/perf/add-response-caching
• mriley/perf/reduce-memory-allocation

Bad Examples (and corrections)

❌ new-feature → ✅ mriley/feat/new-feature ❌ fix-bug-123 → ✅ mriley/fix/authentication-timeout ❌ feat/auth → ✅ mriley/feat/auth ❌ mriley/UpdateCode → ✅ mriley/refactor/update-validation-code ❌ mriley/WIP → ✅ mriley/feat/descriptive-name-here

Quick Reference

Create branch:

git checkout -b mriley/feat/descriptive-name

Switch branch:

git checkout mriley/feat/existing-branch

Rename branch:

git branch -m mriley/feat/new-name

List branches:

git branch -v

Delete branch (local):

git branch -d mriley/feat/old-branch