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