Log the prompt that produced a merged UI change (tiny ADR)

We merge a lot of agent UI now. Six months later someone asks “why does this form validate zip before city?” and the PR description just says “agent polish.” The diff is gone from working memory. The prompt that made the decision is gone too.

I started treating the prompt that shipped like a tiny ADR. Not a ceremony. One short file (or PR note) next to the change so the next human — or the next agent — can see what we asked for, not only what landed.

Keep it under ~15 lines. I use this shape:

## Prompt ADR — ShippingForm zip-before-city (2026-11-05) **Goal:** Require zip before city on blur for US addresses. **Prompt (verbatim):** … **Files touched:** `ShippingForm.tsx`, `shippingValidation.ts` **Rejected alternatives:** city-first (matches old mock); shared schema with Checkout (too wide for this PR) **Follow-ups:** none / link issue Enter fullscreen mode Exit fullscreen mode Verbatim matters. Paraphrase loses the constraints the agent actually obeyed (or ignored).

Commits show outcome. Prompts show intent and guardrails:

Without that, the next agent “simplifies” the awkward bits and reopens bugs you already paid for.

Chat is not a durable design record. Repo is.

You’re editing `ShippingForm` US address validation only. Before you change code, write `docs/prompt-adrs/YYYY-MM-DD-shipping-zip-before-city.md` with: - Goal (one sentence) - This prompt pasted verbatim - Files you expect to touch - Alternatives you will NOT do in this PR Then implement. Do not expand scope. If you need Checkout changes, stop and say so. Enter fullscreen mode Exit fullscreen mode Yes, I ask the agent to write the ADR first. If it skips the file, I bounce the PR before reviewing the UI.

On the next agent UI merge, spend two minutes: paste the prompt into docs/prompt-adrs/…, list files, name one thing you didn’t do. Future you (and the next model) will treat that as source of truth instead of inventing a nicer story from the diff alone.