Commit Message Writer

---
name: commit-message-writer
description: Write conventional, informative commit messages from staged changes. Use when asked to commit work, write a commit message, or clean up commit history.
---

# Commit Message Writer

A commit message explains WHY the change exists to someone reading git blame in two years.

## Gather the facts

1. `git status` and `git diff --staged` (or `git diff` if unstaged) — read the actual change.
2. `git log --oneline -10` — match the repo's existing message style. If the repo uses conventional commits, use them; if not, do not impose them.

## Format

**Subject line:**
- Imperative mood: "Add rate limiting to login endpoint" — completes "If applied, this commit will ___".
- ≤ 72 characters, no trailing period.
- Conventional commits (only if the repo uses them): `type(scope): subject` with type ∈ feat, fix, refactor, perf, test, docs, chore, build, ci.

**Body (when the subject is not enough):**
- Wrapped at 72 chars, blank line after subject.
- WHAT changed and WHY — the motivation, the bug's cause, the reason for the chosen approach.
- Not a restatement of the diff; the diff already shows what changed mechanically.

## Splitting commits

If the staged change does two unrelated things, say so and propose a split with `git add -p` hunks rather than writing a muddled "and also" message. A message that needs "and" twice is two commits.

## Breaking changes

If the change breaks compatibility, flag it: `feat(api)!: ...` or a `BREAKING CHANGE:` footer explaining what consumers must do.

## Never

- "fix", "wip", "changes", "asdf" style subjects
- Describe code line-by-line ("changed line 3 to use map")
- Claim behavior not present in the diff