Git Commit Craftsman

---
name: git-commit-craftsman
description: >
  Produce clean, conventional git commits. Each commit is atomic with a
  meaningful message following the Conventional Commits specification.
  Focus on why the change was made, not just what changed.
---

# Git Commit Craftsman

You craft git commits that tell a clear story of how the codebase evolved.

## Conventional Commits Format

Every commit message follows this structure:

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

[optional body]

[optional footer]
```

### Types (Required)

| Type | When to Use |
|------|-------------|
| `feat` | New feature or capability |
| `fix` | Bug fix |
| `docs` | Documentation only |
| `style` | Formatting, missing semicolons (no logic change) |
| `refactor` | Code change that neither fixes a bug nor adds a feature |
| `perf` | Performance improvement |
| `test` | Adding or correcting tests |
| `chore` | Build process, tooling, dependencies |
| `ci` | CI/CD configuration |
| `revert` | Reverting a previous commit |

### Scope (Recommended)

Use the module, component, or area affected:

- `feat(auth): add OAuth2 login flow`
- `fix(api): handle null response from payment gateway`
- `chore(deps): bump express to 4.19.2`

## Atomic Commits

Each commit contains exactly ONE logical change:

- **DO:** Separate a refactor from a feature — commit each independently
- **DO:** Commit a test fix separately from the code fix it verifies
- **DON'T:** Bundle "fix typo + add new endpoint + update deps" in one commit
- **DON'T:** Commit half-finished work (use stash or WIP branches)

## Subject Line Rules

1. **50 characters or fewer** — hard limit for readability
2. **Imperative mood** — "add feature" not "added feature" or "adds feature"
3. **No period** at the end
4. **Lowercase** first letter after the type prefix
5. **Explain why, not what** — the diff shows what changed; the message says why

### Good Examples

```
feat(cart): support multi-currency checkout
fix(auth): prevent session fixation on login
refactor(db): extract query builder from repository class
perf(images): lazy-load below-fold product images
```

### Bad Examples

```
Updated stuff                     # vague, no type
fix: fixed the bug                # redundant "fixed", no scope
feat(auth): Added new OAuth2 login flow for users to authenticate  # too long, past tense
WIP                               # never commit WIP to shared branches
```

## Commit Body (When Needed)

Add a body when the subject alone doesn't explain the change:

```
fix(payments): retry failed webhooks with exponential backoff

Stripe webhooks were silently failing on timeout. Added retry logic
with exponential backoff (1s, 2s, 4s, max 3 attempts) to prevent
lost payment confirmations.

Closes #142
```

## Breaking Changes

Use `!` after type/scope and add a `BREAKING CHANGE:` footer:

```
feat(api)!: require authentication on public endpoints

BREAKING CHANGE: All /api/v2/* endpoints now require a Bearer token.
Unauthenticated requests return 401 instead of the previous 200.
```

## Pre-Commit Checklist

Before committing, verify:

1. All tests pass
2. Linting passes
3. Only relevant files are staged (check `git diff --staged`)
4. No secrets, credentials, or .env files included
5. The commit message accurately describes the change