LearnGrokAn architecture decision record, or ADR, is useful when a design discussion has produced more material than a future reader can safely reconstruct. These prompts help you turn that material into one reviewable document before implementation begins. They suit technical leads and engineering teams deciding between concrete implementation approaches.
Key point
Record the decision, not the meeting
An ADR should say what the team will do, why alternatives were not chosen, and what work remains before the decision can be relied on.
Start with the source material
Collect the material that actually shaped the decision. Give each item a recognisable name, such as API gateway design notes, Caching spike results, or Platform review meeting, 14 May. Include the ticket or design document that states the problem, not only the notes that propose a solution.
Before pasting anything, separate these inputs:
- The decision the team needs to make.
- Non-negotiable constraints, such as a required interface, supported deployment environment, or data boundary.
- Candidate approaches, including the approach a participant only mentioned briefly.
- Evidence, such as test results, operational incidents, or an agreed product requirement.
- Open questions that could change the result.
Use Extract decision inputs when the material is messy or contradictory. It produces a register rather than an ADR, which prevents a confident draft being built on an unstated assumption.
Watch out
Do not treat a preference as a constraint
A statement such as “we usually use this component” may be useful context, but it is not a requirement unless the source says why the team cannot choose otherwise.
Compare before selecting
Run Compare implementation options when two or more approaches are still credible. Paste the same constraints against every option. Do not describe one option in detail and another with a label only. If an option cannot be compared because its design is not known, record that gap.
The recommendation is a review input, not the decision itself. The decision owner still needs to choose, and the ADR needs to show that choice plainly. Use the comparison to ask focused questions in the review, for example whether a migration path is needed or who will own a new operational alert.
If tool behaviour, supported features, or integration details affect the decision, verify them against the current xAI documentation. These details can be version-dependent. Do not make an ADR depend on a remembered limitation.
Write the record after selection
Use Draft the ADR once the owner has selected an approach. Fill every placeholder before you send it. In particular, name the selected approach and every serious rejected option. A rejected option without a reason will invite the same debate later.
The Decision section should be precise enough for an engineer to tell whether planned work is in scope. For example, it should identify the affected service or boundary, the chosen mechanism, and any explicit exclusion. Avoid statements such as “improve reliability” unless the ADR also says what will change.
Use Challenge the draft ADR in the review meeting or pull request. It is most useful when reviewers have read the document but disagree about what is missing. Work through blockers first. Treat a needs owner or Unknown field as work to assign, not wording to tidy up.
Check
A reader should be able to reconstruct the choice
Give the ADR to someone outside the original discussion. They should be able to name the selected option, the main rejected alternative, the key consequence, and the next owner without asking for the meeting notes.
Check the output against the evidence
Do not check an ADR only for clear prose. Check each claim against a named source document. Look closely at these common failures:
| If you see this | Check this | Do this |
|---|---|---|
| A firm claim with no source | Whether it was stated, tested, or merely inferred | Mark it as an assumption or add the source evidence |
| A rejected option described unfairly | Whether its actual advantages and constraints are recorded | Rewrite the option from the original notes |
| A consequence with no owner | Whether someone must change monitoring, support, deployment, or documentation | Add a follow-up item with completion evidence |
| An open question hidden in prose | Whether its answer could reverse the decision | Move it to Assumptions and unresolved questions |
Run Prepare the accepted ADR only after review comments have explicit resolutions. Its publication check is the final gate. Store the finished record beside the design material or codebase where the implementing team will find it.
Stop
Do not erase disagreement to make approval easier
If a material uncertainty remains, record it and assign the work needed to resolve it. A neat but false record creates more rework than an incomplete one.
When the prompts do not produce a usable ADR
If the output contains many Unknown fields, do not keep rewriting the prompt. The decision is not ready for a durable record. Return to the decision owner with the missing questions, then rerun the input register and comparison.
If the model selects an option despite equal or incomplete evidence, remove the recommendation from the draft and ask the owner to decide. If the record becomes too broad, split it into separate decisions. One ADR should capture one decision with one accountable owner, even when several components are affected.
