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

Good	Bad	Why
42-build-caching	42	Too vague
15-null-ptr-fix	15-fix-the-bug-where-null-pointer-exception-occurs	Too long
28-refactor-parser	28-misc-changes	Not descriptive

Commit Message Conventions

Keywords for Issue Linking

Keyword	Effect	Use When
Fixes #N	Closes issue when PR merges	Work completely resolves the issue
Closes #N	Closes issue when PR merges	Same as Fixes
Refs #N	Links without closing	Work is partial or related

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

Branch State	PR State	Inferred Issue Status
Branch exists, no PR	-	In-progress
Branch exists, draft PR	Draft	In-progress
Branch exists, open PR	Open (ready)	Ready to Review
Branch merged	PR Merged	Done
Branch deleted, PR closed	Closed (not merged)	Work abandoned, check issue

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