commit-trailers

Commit Trailers -- Structured Decision Context

Supplement conventional commits with structured trailers that preserve the reasoning behind a change. Future maintainers (and future agents) read commit history to understand not just what changed, but why a specific approach was taken.

Standard Trailers

Add these after the commit body, separated by a blank line, when they add value:

Constraint: <external limitation that shaped this approach>
Rejected: <alternative considered and the reason it was rejected>
Confidence: high | medium | low  <how certain we are this is correct>
Scope-risk: low | medium | high  <blast radius — how much can this break>
Not-tested: <what was not tested and why>

---

When to Use Each Trailer

Trailer	When to Include	When to Skip
Constraint	External limitation forced a non-obvious decision	No external constraints applied
Rejected	A reasonable alternative was considered and discarded	Only one approach was viable
Confidence	Correctness is uncertain or untested in key areas	Straightforward well-tested change
Scope-risk	Change touches shared infrastructure, middleware, auth, or core data paths	Isolated, single-purpose change
Not-tested	A gap in test coverage is intentional and known	All paths are tested

Not every commit needs trailers. A fix: typo in error message needs none. A new auth middleware affecting every API call needs all five.

---

Trailer Reference

Constraint

An external limitation — browser API, hosting restriction, library limitation, business rule, or environment constraint — that ruled out the obvious solution.

Constraint: Safari 15 does not support the CSS :has() selector
Constraint: Redis unavailable in staging — in-memory fallback only
Constraint: Must stay on Node 18, no upgrade path in scope
Constraint: Third-party payment API does not support idempotency keys

Rejected

An alternative that was seriously considered. Helps future maintainers understand why the current approach exists instead of the simpler-looking one they are thinking of.