Write an ADR

Write an Architecture Decision Record (Nygard style: Title / Status / Context / Decision / Consequences, plus an explicit Alternatives section) for the decision described in $ARGUMENTS.

If $ARGUMENTS is empty, infer the decision from the current branch, recent commits, or uncommitted diff (git log --oneline -20, git diff); if nothing points to a clear decision, ask the user what to record and stop. Do not invent a decision.

Locate and match existing convention

• Find where ADRs live: check docs/adr/, docs/decisions/, doc/adr/, adr/, .adr-dir, or paths named in CONTRIBUTING/README. If a Makefile/adr-tools config exists, follow it (e.g. run adr new "<title>" instead of hand-writing the file, so tooling assigns the number and links the index).
• If prior ADRs exist, open the two most recent and copy their exact numbering scheme, filename pattern, heading structure, and status vocabulary. These win over any default below when they differ.
• If none exist, create docs/adr/ and number 0001. Filename: NNNN-kebab-title.md (e.g. 0007-use-postgres-for-event-store.md).
• Determine the next number by scanning existing NNNN-* files and incrementing the highest.

Investigate before writing

Do not write from assumptions. Ground each section in the code:

• Read the files, configs, and dependencies the decision touches so Context and Consequences cite real specifics (module names, versions, constraints), not generalities.
• Establish the actual forces: performance, cost, team skills, existing stack, deadlines, operational burden, migration cost. State them, don't hand-wave.
• Get the real date with git log -1 --format=%cd --date=short or the system date. Never guess.

Structure (Nygard ADR)

Produce these sections. If the repo's existing ADRs use a different heading set or status vocabulary (see above), follow theirs instead; the list below is the default only:

1. # NNNN. <Short imperative title> — the decision as a phrase, e.g. "Use Postgres for the event store".
2. ## Status — the repo's status vocabulary if it has one; otherwise one of Proposed / Accepted / Deprecated / Superseded (link the superseding ADR if any). Add the date.
3. ## Context — the problem, the forces and constraints driving it, why a decision is needed now. Written so a new hire understands the situation without prior knowledge. No solution here.
4. ## Decision — what was chosen, in active voice as a stated commitment ("We will adopt...", "We are using..."). State the choice precisely enough to act on, including scope and key parameters.
5. ## Alternatives considered — every serious option including the chosen one and the null/do-nothing option. For each: one-line summary, Pros, Cons, and an explicit "Rejected because..." (omit for the chosen one). Compare on the same forces named in Context.
6. ## Consequences — Positive, Negative, and Follow-ups (concrete action items: migrations, docs, deprecations, tickets to open). Include what becomes harder, not only easier.

Rules

• Be honest about trade-offs. If the chosen option has real downsides or debt, name them in Negative — an ADR that lists only upsides is worthless.
• Record the decision at the time it was made; do not retro-edit past ADRs. Supersede instead of rewriting.
• Every claim must be checkable: cite the file, benchmark, constraint, or requirement behind it. Cut adjectives that carry no information ("robust", "scalable", "clean").
• Keep it tight — one page. Detail belongs in Context and Alternatives, not in padding.
• If the ADR directory has an index, README, TOC, or adr-tools-maintained list, add the new ADR to it (unless the tooling already did). An ADR that nothing links to gets lost.
• Write the file, update any index, then report the path and the one-line title. Do not commit unless asked.