# 0029. A commit may carry a short body for a non-obvious why

- **Status:** Accepted
- **Date:** 2026-08-08

## Context

`docs/COMMIT.md` required a single line. That left a seam: a fix with a surprising cause has nowhere to put
the cause. It is not a decision, so it does not warrant an ADR, and the subject line has no room for it.

This codebase produces exactly that kind of finding. `6d9a014` fixed a day count taken from a timestamp
difference, which is one hour short across the March daylight-saving change and billed one day less;
`49e84e1` fixed a double slash appearing in absolute URLs. In both cases the *what* is in the diff and the
*why* was lost.

## Decision

**One line stays the norm. A body of two or three lines is allowed when the reason is not visible in the
diff.**

- The subject line still says *what*, in the imperative, with no closing period.
- The body follows a blank line and exists only for a cause the diff cannot show.
- If the reason is visible in the diff, there is no body.
- A **decision**, as opposed to a surprise, is still an ADR. The body does not become a place to record
  choices.

## Alternatives

- **A bug-driven ADR for each such finding**, as the sibling Molino project does, with real command output
  and measured numbers in the Context. It produces a better record, and it is too much ceremony for a
  one-line cause — the ADR log is for decisions, and filling it with defects makes it harder to search for
  the decisions.
- **Keeping the strict single line** and accepting the loss. The information is most valuable exactly where
  someone will hit it: `git blame` on the line that looks wrong.

## Consequences

- The seam closes at the cost of a judgement call per commit — "is this visible in the diff?" — which will
  sometimes be answered wrongly in both directions.
- `git log --oneline` is unaffected; the history stays scannable.
- The rule is easy to abuse into a progress narrative. Two or three lines is the limit, and the body is for a
  cause, never for a summary of the change.