ADR authoring

When to write one

Write an ADR if any of:

• The decision has plausible alternatives a future engineer might prefer.
• The decision overrides a default in this toolkit (skill says X, we do Y).
• The decision waives a harness gate (mutation, coverage, OpenAPI breaking, CVE).
• The decision constrains future work (e.g. "we will not use Kafka in this module").

Do not write an ADR for:

• Choices uniquely forced by the source ticket.
• Trivial mechanical decisions (variable naming).

File layout

.specs/<feature-id>/adr/NNN-<slug>.md where NNN is zero-padded and unique per feature.