Write the decision
you already made.
Fill in what you decided and what you turned down. Get a formatted architecture decision record you can commit straight into your repository. It runs in your browser — nothing is uploaded, and there is no account.
Fill it in, copy it out
Loaded with a real example so you can see the shape before you replace it. Nothing leaves your browser — there is no server to send it to.
Your decision
docs/decisions/retry-with-exponential-backoff-and-jitter.md# Retry with exponential backoff and jitter - Status: Accepted - Date: 2026-08-13 - Deciders: platform ## Context A fixed five-second retry took production down on the 9th. Every client that failed during the outage woke at the same moment and hit an empty connection pool, so the recovery attempt became a second outage lasting longer than the first. ## Decision All service-to-service retries use exponential backoff with full jitter, capped at 30 seconds and five attempts. The shared client owns this so no service implements its own. ## Alternatives considered - **Keep the fixed 5s delay** — It is what caused the thundering herd on the 9th, and it hides the real bug behind an apparently healthy retry. - **Circuit breaker only** — Correct, and roughly three weeks of work. Worth doing later; it does not solve the incident in front of us. - **Retry in the load balancer** — Moves the problem out of our code and out of our visibility. No per-call context to decide what is safe to repeat. ## Consequences Worst-case latency on a failing dependency rises from 15s to about 60s, which we accept. Anything needing a tighter bound must fail fast and surface the error rather than shorten the backoff.
One decision, one file, no editing afterwards
The standard ADR shape, because it is a good format that survives being read by someone who was not in the room.
Context and decision
What forced the choice and what you settled on, written so it still reads correctly to someone who joins the team next spring and has never seen the incident that caused it.
Rejected alternatives
Every option you considered and why it lost. This is the expensive knowledge — a team that cannot see the road not taken will propose it again next quarter and spend the same fortnight rejecting it.
Consequences accepted
What this makes harder, and what you agreed to live with. A decision recorded without its cost reads as a recommendation, and the next person will not trust it.
A committable file
Markdown with a stable, numbered filename ready for docs/decisions/. Compatible with adr-tools and Log4Brains, and equally fine with no tooling whatsoever.
Three steps, about a minute
Paste the context
A pull request and its review comments work best, because the argument is usually in the comments. A design doc, an incident report or a plain paragraph all work too.
Check the rejected options
This is the section worth reading closely. If an option you seriously considered is missing, add a line about it — that is the part your future team will search for.
Commit it next to the code
Drop it in docs/decisions/ and commit it with the change it describes. A record that lands in the same commit as the work is a record nobody has to go back and write.
This writes one record. The habit is the hard part.
Worth saying plainly on the page rather than discovering it in three weeks.
Why teams abandon ADRs
Not because the format is wrong — it is a good format. Because writing the record is a separate act of will after the work is finished, and that act is the first thing cut in a busy week. Most ADR directories stop at number four.
What removes the willpower
An agent that reads the commits and the review thread and writes the record without being asked, then links it to everything it touches and answers questions from the archive later. Same format, no discipline required.
Before you paste anything in
01What is an architecture decision record?+
02Do I need an account?+
03What should I paste in?+
04What format does it produce?+
05Is this the whole product?+
06Can I use the output commercially?+
If the format is not your problem
Documentation that keeps the why
The agent that writes these from your commits, pull requests and incidents without being asked.
ADR vs wiki
Two formats that fail in opposite ways. Which failure do you currently have?
Why agents need the why
Your coding agent will refactor away a constraint whose reason it cannot see.
One record is a document. A hundred is an archive.
The generator writes the first one. The product writes the rest, from work that already happened.