name: branch-naming description: Defines branch naming conventions for issue work. Use when creating branches for issues, understanding work status from branches, or linking commits to issues.

Branch Naming Conventions

Purpose

This skill establishes consistent branch naming conventions that:

1. Clearly link branches to GitHub issues
2. Enable automated detection of work status
3. Support the issue-review skill in determining issue states

Branch Naming Format

Standard Pattern

<issue-number>-<short-description>

Examples:

• 42-build-caching
• 15-linker-error-fix
• 28-simplify-job-system

Claude-Specific Branches

When Claude Code creates branches, use this pattern:

claude/<issue-number>-<short-description>-<session-id>

Examples:

• claude/42-build-caching-Abc12
• claude/15-linker-error-Xyz99

The session ID suffix ensures uniqueness across multiple Claude sessions.

Naming Rules

DO:

• Start with the issue number
• Use lowercase letters and hyphens only
• Keep descriptions short (2-4 words)
• Use descriptive slugs that summarize the work

DON'T:

• Use spaces or underscores
• Include special characters (except hyphens)
• Create overly long branch names (max ~50 chars)
• Omit the issue number for issue-related work

Examples

Commit Message Conventions

Keywords for Issue Linking

Examples

Add build result caching

Implement file-based caching for compilation results.

Fixes #42

Extract cache module

Move caching logic to dedicated module.

Refs #42

Detecting Work Status from Branches

The issue-review skill can determine issue status by analyzing branches:

Branch Detection

# Find branches for a specific issue
git branch -a | grep -E "^[^/]*${ISSUE_NUMBER}-|/${ISSUE_NUMBER}-"

# Or using GitHub CLI
gh pr list --search "head:${ISSUE_NUMBER}" --state all --json number,state,isDraft,headRefName

Status Inference

Workflow Integration

Starting Work on an Issue

1. Create branch:

   git checkout -b 42-build-caching
   

2. Make commits with issue references:

   git commit -m "Implement cache storage
   
   Refs #42"
   

3. Create PR:

   gh pr create --title "Add build caching (#42)" \
     --body "Implements build result caching.
   
   Fixes #42"
   

Issue-Review Integration

The issue-review skill uses branch/PR information to:

1. Detect work in progress:

   • Search for branches containing issue numbers
   • Check for draft PRs linked to issues

2. Verify status accuracy:

   • Issue marked "Ready to Review" should have an open PR
   • Issue marked "In-progress" should have a branch or draft PR
   • Issue marked "Done" should have a merged PR

3. Identify stale work:

   • Branches with no commits in 14+ days
   • Draft PRs with no updates in 7+ days

Quick Reference

Branch Naming

<issue>-<description>           # Standard
claude/<issue>-<desc>-<session> # Claude sessions

Commit Keywords

Fixes #N    # Closes issue on merge
Closes #N   # Closes issue on merge
Refs #N     # Links without closing

Status Detection

Branch only           → In-progress
Branch + Draft PR     → In-progress
Branch + Open PR      → Ready to Review
Merged PR             → Done
No branch/PR          → Check issue status

Guidelines

• Always include issue numbers in branch names for trackable work
• Keep branch names concise but descriptive
• Reference issues in commits for traceability
• Use closing keywords only when work fully resolves the issue
• Delete branches after PR merge to keep repository clean