Architecture decision record from design options

Use one fixed comparison pass before you write an ADR. It turns a design discussion into a record that names the chosen option, the rejected options, the constraints that drove the choice, and the work still open. This is for leads and senior developers who need a decision others can challenge and implement.

The working habit is simple: prepare an evidence pack, ask the model to compare only against stated constraints, then review the ADR as a decision document rather than accepting it as prose.

1. Build the decision pack

Collect the source material before opening a chat. Do not ask the model to reconstruct the problem from an architecture diagram and a few messages.

Create a document with these sections:

1. Decision statement: one sentence describing the choice. For example: Choose a delivery mechanism for audit events from the billing service to the data platform.
2. Scope: name the service, interface, deployment boundary, and teams affected.
3. Constraints: list non-negotiable conditions separately from preferences. Include operational ownership, failure handling, data classification, migration limits, delivery deadline, and compatibility requirements where relevant.
4. Success measures: state what acceptable operation looks like. Use observable conditions, such as whether consumers can replay events, whether a failed delivery is visible to on-call staff, or whether a rollback avoids data loss.
5. Options: give every proposal the same level of detail. Include a short design, dependencies, migration path, operational model, and known risks.
6. Evidence and unknowns: paste links or extracts from existing specifications, incidents, code investigations, and test results. Mark claims that have not been verified.

Keep facts separate from opinions. The current worker retries for 24 hours is a fact to verify. A queue will be easier to operate is an assertion that needs conditions and evidence.

If your material contains internal code, customer data, credentials, or incident details, apply your organisation's approved data-handling process before sharing it. Check the xAI documentation overview for current product and data-handling details, as these can be version-dependent.

2. Make the comparison repeatable

Use the same prompt structure for every decision. This matters more than finding clever wording. A fixed structure makes gaps visible across ADRs and stops the model from giving one option more scrutiny than another.

Paste the decision pack, then use a request like this:

Act as a technical design reviewer. Produce a comparison before drafting an ADR.

Decision: [paste decision statement]
Scope: [paste scope]
Constraints: [paste numbered constraints]
Success measures: [paste measures]
Options: [paste each option]
Evidence and unknowns: [paste material]

Rules:
- Treat numbered constraints as mandatory unless explicitly labelled a preference.
- Do not invent implementation facts, costs, test results, ownership, or operational capabilities.
- For every option, state compliance with each constraint as meets, partly meets, does not meet, or unknown.
- Explain each assessment by referring to the supplied material.
- Separate assumptions from evidence.
- Identify the smallest experiment or investigation that would resolve each material unknown.
- Recommend an option only if its remaining risks and unknowns are explicit.

Return:
1. Constraint comparison table.
2. Recommendation and rationale.
3. Rejected options and why they were rejected.
4. Assumptions requiring confirmation.
5. Follow-up decisions, owners, and decision deadlines where supplied.
6. A draft ADR in the template below.

Follow it with your ADR template. A compact template is enough:

Status: Proposed
Date:
Owners:
Decision:
Context:
Constraints:
Considered options:
Decision drivers:
Chosen option:
Consequences:
Rejected options:
Assumptions:
Follow-up decisions:
Validation and rollback:

Do not ask for a recommendation without requiring the comparison table first. The table exposes the reasoning that a polished ADR can conceal.

3. Review the comparison before the ADR

Read the constraint table line by line. You are checking the decision logic, not grammar.

For each meets or partly meets entry, ask three questions:

• Does the cited evidence actually support the assessment?
• Has the option been judged against the exact constraint, rather than a nearby and easier claim?
• Would the assessment still hold during deployment, failure recovery, and on-call operation?

Pay special attention to asymmetric detail. If one option has a concrete migration plan and another says can be migrated incrementally, the second option is not comparable yet. Return it for detail rather than treating vague wording as lower risk.

Use a short decision review with the people who own the affected systems. Ask them to challenge the constraint interpretation, evidence quality, and operational consequences. Do not begin by debating the recommendation. If the inputs are wrong, a unanimous recommendation is still wrong.

4. Convert the draft into an ADR your team can use

Edit the draft yourself. Keep the final ADR concise, but retain enough detail that a developer joining later can understand why a plausible option was rejected.

Make these changes before publishing:

1. Replace generic claims, such as more scalable or simpler, with the specific constraint and consequence. Write avoids a coordinated client deployment required by C3, not easier migration.
2. Move unverified statements into Assumptions. Give each one an owner and a date or decision point.
3. Name rejected options even if they were popular. State the condition that ruled them out.
4. Turn unresolved choices into Follow-up decisions. For example: Decide retention period before enabling replay for production consumers.
5. Add Validation and rollback. Say what signal confirms the decision works, who watches it, and what change is reversed if it does not.

The ADR should record a decision, not pretend uncertainty has disappeared. A proposed decision can contain open work, provided that work is visible and bounded.

5. Tell when the output is wrong

The most common failure is false certainty. The model may make a coherent recommendation from incomplete material, or convert a preference into an implied requirement. Treat smooth prose as a reason to inspect the evidence more closely.

Use this check before marking the ADR accepted:

If you see this	It usually means	What to do
A recommendation with no failed constraint for other options	The trade-off was not made explicit	Ask which constraints each rejected option fails or weakens
A claim not traceable to the decision pack	The output added an assumption	Remove it or label it as an assumption with an owner
Unknown items in the chosen option with no follow-up	Risk has been deferred silently	Add an experiment, owner, and decision point
A rejected option described only as complex	The rationale is opinion, not a decision record	Name the migration, operating, compatibility, or failure consequence

6. Repeat the habit after the decision

Store the final ADR with the specification or repository where implementation work starts. Link the follow-up decisions from the delivery plan and revisit them when the stated trigger occurs, such as a migration milestone or the first production incident.

When the result does not work, do not keep rewriting the prompt. Go back to the decision pack. Add the missing constraint, obtain the missing evidence, or split one overloaded decision into two smaller ADRs. Then run the same comparison again. The useful output is not the first recommendation. It is a decision record whose assumptions can survive contact with implementation and operations.