Writing Commit Messages

---
name: writing-commit-messages
description: Use when drafting any commit message — sets format (imperative subject under 72 chars, explanatory body when the why isn't obvious from the diff) and prevents the "Fix X" one-liner reflex for non-trivial fixes
---

# Writing Commit Messages

## Overview

A commit message is the only place future-you (or future-them) finds out WHY a change happened. The diff shows what; the message has to explain why. The honest agent default is a one-liner subject and no body — fine for trivial changes, lossy for everything else.

**Core principle:** The message answers "why," not "what." The diff already shows what.

## The Format

```
<subject — imperative, under 72 chars, capitalize first letter, no period>
<blank line>
<body — wrap at 72 cols, explain WHY this change exists>

<blank line, optional>
<trailer — e.g. Fixes #123, Co-Authored-By: ...>
```

## Subject Line

- **Imperative mood:** `Fix login failure for apostrophe usernames` — not `Fixed`, not `Fixes`, not `Fixing`.
- **Under 72 chars** (50 ideal). If you need more, the body should be doing that work.
- **No trailing period.**
- **Capitalize the first letter.**

## When To Write a Body

Write a body when ANY of these are true:

- The change fixes a bug — the body explains the root cause and the failure mode
- The change is non-obvious from the diff alone
- The change has a non-obvious motivation (compliance, perf regression, deprecation)
- The change is part of a larger initiative — link to the spec or parent ticket
- The change has subtle behavior (silent failure, edge case, race-condition fix)

Skip the body for: pure renames, formatting / lint fixes, dep version bumps with no behavior change, typo fixes in non-code files.

## Body Content

Include:

- **Symptom / motivation** — what was wrong, or why this exists
- **Root cause** — why the bug existed (for fixes)
- **Approach** — only if non-obvious (`We chose X over Y because Z`)
- **Caveats / follow-ups** — known limitations, deferred work

Leave out: play-by-play of the diff, redundant restatement of the subject, marketing speak.

## Before / After

❌ **One-liner reflex (loses the why):**
```
Fix login bug
```

❌ **What-not-why (diff already shows this):**
```
Update src/auth/validator.ts

Removed the .replace() call in validator.ts.
```

✅ **Subject + body that explains the why:**
```
Fix silent login failure for usernames with apostrophes

The validator was stripping apostrophes via .replace(/'/g, '') before
the database lookup, so users like "O'Brien" were queried as "OBrien"
and silently never matched. Removing the replacement passes the
username through unchanged.

Fixes #482
```

## Common Mistakes

| Mistake | Fix |
|---|---|
| Past-tense subject (`Fixed apostrophe bug`) | Imperative: `Fix apostrophe bug` |
| Subject longer than 72 chars | Move detail to the body |
| Body that restates the subject | Cut it; explain why instead |
| Body that walks through the diff | Cut it; reader can read the diff |
| No body on a non-trivial bug fix | Add one — what was broken, why, how this fixes it |
| `Misc improvements` / `Various fixes` | One logical change per commit. Split first. |
| Mentioning a ticket number without context | Either explain in the body or just leave the trailer |

## Red Flags — STOP

- Subject starts with a past-tense verb
- Subject is your only content for a non-trivial fix
- Body is a list of what you changed (= what the diff shows)
- Multiple unrelated changes in one commit — split first
- About to commit a bug fix with no body explaining the root cause