---
name: commit-message-guide
description: Guide for creating well-structured conventional commits. Use when creating git commits, drafting commit messages, or reviewing commit message quality.
---

# Commit Message Guide

This skill ensures commit messages follow conventional commit format with command tense and concise, meaningful content.

## Commit Message Structure

### Format

```
<type>(<scope>): <subject>

[optional body]

[optional footer]
```

### Type

Use one of these conventional commit types:
- `feat`: New feature
- `fix`: Bug fix
- `refactor`: Code change that neither fixes a bug nor adds a feature
- `perf`: Performance improvement
- `style`: Code style changes (formatting, missing semicolons, etc.)
- `test`: Adding or updating tests
- `docs`: Documentation changes
- `build`: Build system or dependency changes
- `ci`: CI/CD configuration changes
- `chore`: Other changes that don't modify src or test files

### Scope (optional)

The scope provides context about what area of the codebase is affected. Use appropriate scope for the module/component being changed, e.g.:
- `api`, `auth`, `db`, `ui`, `config`, `cli`, `core`

### Subject

- Use **command tense** (imperative mood): "Add feature" not "Added feature" or "Adds feature"
- Keep it concise (50 characters or less ideally, 72 max)
- No period at the end
- Lowercase after the type prefix

Examples:
- `feat(api): add support for batch operations`
- `fix(auth): handle expired token refresh`
- `refactor(db): simplify query builder logic`

Bad examples:
- `feat(api): Added support for batch operations` (wrong tense)
- `Fixed a bug in auth` (missing type/scope, wrong tense)

## Body Guidelines

**Only include a body when the title and file changes alone cannot reasonably convey the reason for the commit.**

### What to Include

- **Why** the change was made (if not obvious)
- **Architectural decisions** and their rationale
- **Trade-offs** considered
- **Context** that won't be visible from the diff

### What to Exclude

- Information visible on GitHub (files changed, lines added/removed, diff stats)
- Test status information ("All tests pass")
- Time-related information (estimates, time spent)
- Obvious information (implementation details visible in the diff)
- AI authorship or attribution (no "Generated with Claude Code", Co-Authored-By tags, emojis, or tool attribution)

### Example Good Bodies

```
feat(api): add support for webhook callbacks

Implements webhook delivery for event notifications.
Uses a retry queue with exponential backoff to handle
transient failures without losing events.
```

```
refactor(db): restructure query parser

Reorganizes query parsing to use a table-driven approach
instead of a large switch statement. This makes it easier
to add new query types and reduces code duplication.
```

### Example Bad Bodies

```
fix(auth): correct token expiry handling

Changes 3 files with 45 additions and 12 deletions.
All tests pass.
This fix took longer than expected, about 2 days.
```

## Special Commit Types

### WIP Commits

```
WIP: debugging race condition in scheduler
```

These don't need to follow strict formatting and may have failing tests.

### FIXUP Commits

```
fixup! feat(api): add support for webhook callbacks
```

Created with `git commit --fixup=<commit-hash>` for automatic squashing during rebase.

## Pre-Commit Checklist

Before creating a commit, verify:

- [ ] **GitHub account**: Verified per the account probe in `claude/references/github-auth-probe.md` (extract `{owner}/{repo}`, probe with `gh api`, switch accounts if needed)
- [ ] Code builds successfully
- [ ] All tests pass
- [ ] Code is formatted (run formatter)
- [ ] Code is linted (if applicable)
- [ ] Commit type is appropriate
- [ ] Subject uses command tense
- [ ] Subject is concise and clear
- [ ] Body (if present) adds value beyond the diff
- [ ] Body doesn't include GitHub-visible information
- [ ] Body doesn't include test status or time estimates
- [ ] No AI attribution, co-author tags, or tool attribution

**Exception**: WIP or FIXUP commits may skip these requirements.

## Examples

### Minimal Commit (No Body Needed)

```
feat(ui): add variable binding display command
```

The title clearly describes what was added. The diff will show the implementation.

### Commit with Useful Body

```
perf(core): optimize instruction dispatch loop

Replace computed goto with direct threaded code. This
reduces dispatch overhead by eliminating one memory
indirection per instruction. Trade-off is slightly
larger binary size due to code duplication.
```

### Commit with Unnecessary Body

```
fix(db): handle empty name table

Modified src/db.zig to add a check for empty tables.
Updated tests to cover this edge case. All 47 tests pass.
This was a quick fix, only took about an hour.
```

None of this information adds value.

## When Creating Commits

1. **Draft the commit message** following this guide
2. **Show the draft** to the user before committing
3. **Ask for feedback** if the commit is complex or touches multiple concerns
4. **Ensure the body adds value** - when in doubt, omit the body
5. **Include only relevant context** in the body
6. **NEVER add AI attribution** - no tool attribution of any kind
7. **Use multiple `-m` flags for commits** -- never use `$(...)` or heredoc patterns in git commit commands:
   - Subject only: `git commit -m "type(scope): subject"`
   - Subject + body: `git commit -m "type(scope): subject" -m "Body paragraph."`
   - Subject + body + footer: `git commit -m "type(scope): subject" -m "Body paragraph." -m "BREAKING CHANGE: description"`