From technical choice to preserved rationale

Keep the why with the decision.

An architecture decision record explains a technical choice, its constraints, alternatives and consequences—and whether it is implemented.

Make this with my agent

Bring your notes. Review a draft before sharing.

Explore the method

01
Accepted is not implemented.
Ada accepted ADR-007. Implementation is not yet complete.
02
Keep the cost visible.
A reviewed snapshot can be stale until its next generation.
03
Preserve the history.
A changed decision needs a new reviewed record, not a rewritten past.

THE REAL HTML · FICTIONAL EXAMPLEView on its own

A worked example, not a customer result. September 2026 dates are sample facts.

Now make it about your work

Your constraints. Your agent. The reason for the choice.

Bring the reviewed decision and real alternatives. Keep acceptance, implementation and consequences separate.

Start with three things

The bounded question and verified constraints.
Alternatives, evidence and the actual decision state.
Consequences, implementation status and the authoritative record.

Make this with my agent

You review the facts and access. Nothing is published without your approval.

The method behind the recordFrom a technology choice to an explicit tradeoff

How can an agent help create an architecture decision record?

Supply the problem, constraints, alternatives considered, and the actual decision state. Ask your agent to explain the chosen tradeoff and its consequences without inventing requirements or approval. Review the record, keep the authoritative version with your team's engineering records, and share an approved static reading companion when that helps other readers.

What to give your agent

The specific architectural question, affected scope, and verified functional or operational constraints.
Alternatives actually considered, supporting evidence, and uncertainties—not invented benchmark results.
The exact proposed, accepted, rejected, or superseded state with its owner, date, and source record when supplied.
Positive and negative consequences, implementation status, and the established review or supersession process.

Write the constraint before the choice
Explain what the design must accomplish and what the team knows. Keep a requirement separate from a preference or assumption. Narrow the scope so a choice for one documentation page does not read as an organization-wide architecture mandate.
Compare the real alternatives
Show each option against the same supplied constraints and preserve the reason the team preferred one. Mark unmeasured performance, unknown operational effort, and unresolved requirements honestly. A diagram can clarify boundaries, but it should not invent infrastructure.
Keep decision state and implementation separate
A proposal is not an accepted record, and an accepted decision may not yet be implemented. Preserve the actual approval evidence and consequences, including the costs the team knowingly accepts. The agent should not make the decision sound unanimous when no such agreement is documented.
Preserve the history when context changes
Keep the source record in the established engineering workflow. If the decision changes, follow the team's supersession process rather than silently rewriting why the earlier choice was made. An HTML companion can help non-specialists read it, but should state its snapshot date and source status.

Keep creating and revising in the agent you already use. Start with a saved artifact style and learn how to update HTML without changing its link.

Use the full promptReady for your agent and your notes

Use the conversation where you already did the work. Only attach material you are allowed to share.

Get the ready-to-copy creation request →

Create an architecture decision record companion from only the authorized requirements, alternatives, evidence, and decision records I provide. Ask for missing essentials: scope, constraints, actual alternatives, decision state, owner, source date, and consequences. Separate requirements from assumptions, proposed from accepted decisions, and acceptance from implementation. Preserve negative consequences and unresolved evidence. Do not invent benchmarks, security guarantees, consensus, requirements, or approval. Explain why the chosen tradeoff fits this scope, not why a technology is universally best. Keep sensitive infrastructure and credentials out of the shared version. State the authoritative record and supersession process without silently rewriting history. Create static HTML with no scripts, forms, or live system claims. Apply my saved artifact style if available. Show the draft and unresolved questions. Do not publish or change access without separate explicit approval. Do not edit the architecture, deploy changes, or mark a record accepted as part of drafting.

Check before you shareAccuracy, clarity, and permission

Is the specific scope and governing constraint understandable before the solution?
Are alternatives and consequences grounded in the actual evidence?
Are proposed, accepted, superseded, and implemented states distinguished?
Does the record retain negative tradeoffs and unmeasured claims honestly?
Is the authoritative history preserved, with sensitive engineering details appropriately limited?

When HTML fits

A readable companion to a reviewed technical decision when stakeholders need the context and consequences without navigating the whole repository.

When another format fits better

Keep authoritative decision history with the engineering team's chosen records and use its review process. If the repository's Markdown already works for the audience, share that. This page does not review system security, choose an architecture autonomously, or implement the decision.

What we started withThe same facts, as a wiki page

Fictional team wiki

ADR-007 — Cedar Docs reading-page delivery

Status

Accepted September 7, 2026, by Ada in the repository decision record. Acceptance is documented; implementation is not complete. The repository record remains authoritative, though its URL is not supplied.

Scope and requirements

Scope is one public documentation reading page, not operational dashboards or every application. Readers need a daily reviewed summary that remains readable without a live data connection at reading time. Only reviewed audience-safe content belongs in it. Daily review is the intended process, not a service-level guarantee; no exact schedule, hosting service or real-time guarantee is required.

Alternatives and decision

Alternatives: live queries at page load, which depend on a connection when reading, or generated snapshots after review, which separate generation from reading. We chose reviewed snapshots for reading-time independence. No benchmarks, costs, capacity, uptime measurements or security audit are supplied; this is not a claim that snapshots are universally superior or prove security.

Consequences and implementation

Ada accepts that content can be stale until the next reviewed generation. No automatic refresh job or exact generation guarantee exists in this record. An implementation owner, due date, deployment and verification result remain unspecified.

Decision history

A changed decision needs a new reviewed record superseding ADR-007 while preserving its history and rationale. An HTML companion does not accept another decision, update the repository or deploy the architecture.

Inspect the HTMLOne self-contained file

The example is sanitized and isolated from this site. No scripts, forms, or live data.

<!doctype html><html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width, initial-scale=1"><title>Cedar Docs · ADR-007</title><style>
*{box-sizing:border-box}html{color-scheme:light}body{margin:0;background:#f5f8fc;color:#182e46;font:17px/1.65 system-ui,sans-serif}main{max-width:1000px;margin:auto;padding:clamp(20px,5vw,64px)}h1,h2,h3,p{margin:0 0 18px}h1{font:500 clamp(32px,5vw,58px)/1.14 Georgia,serif;letter-spacing:-.025em;overflow-wrap:anywhere}h2{font:500 29px/1.3 Georgia,serif;overflow-wrap:anywhere}h3{font-size:19px;line-height:1.4}.label{font:700 12px/1.6 system-ui,sans-serif;letter-spacing:.08em;text-transform:uppercase}.intro{font-size:20px}.lead{background:#23486b;color:white;padding:24px;margin:28px 0}.lead p:last-child{margin:0}.grid{display:grid;grid-template-columns:repeat(auto-fit,minmax(min(100%,230px),1fr));gap:20px;margin:24px 0}.card{background:white;border:1px solid #bbc5c4;padding:24px}.metric{font:500 38px/1.2 Georgia,serif;display:block;margin-bottom:12px}section{margin:36px 0}ul,ol{padding-left:22px}li{margin-bottom:12px}.note{font-size:14px}.warning{border-left:5px solid #956118;padding-left:20px}a{color:inherit;text-underline-offset:4px}a:focus-visible,summary:focus-visible{outline:3px solid #956118;outline-offset:4px}table{width:100%;border-collapse:collapse;table-layout:fixed;font-size:15px}th,td{text-align:left;vertical-align:top;border-bottom:1px solid #bbc5c4;padding:12px 8px;overflow-wrap:anywhere}caption{text-align:left;font-weight:700;padding:12px 0}pre,code{white-space:pre-wrap;overflow-wrap:anywhere}footer{border-top:1px solid #bbc5c4;padding-top:24px;margin-top:40px;font-size:14px}@media(max-width:480px){th,td{padding:10px 4px;font-size:14px}}@media print{body{background:white}.card,.lead{break-inside:avoid}h2,h3{break-after:avoid}}
</style></head><body><main><header><p class="label">Fictional ADR-007 / Accepted September 7, 2026</p><h1>A reviewed snapshot, not a live query.</h1><p class="intro">Cedar Docs public documentation reading page · Technical decision owner: Ada.</p></header>
<section class="lead"><h2>Decision accepted. Work not yet complete.</h2><p>Use generated snapshots after review so the page remains readable without a live data connection at reading time.</p></section>
<section><h2>The constraint comes first</h2><p>Readers need a daily reviewed summary, not live operational data. This decision covers one public documentation reading page—not operational dashboards or every application.</p><p>Only reviewed audience-safe content belongs on the page. Daily review is the intended process, not a proven service-level guarantee.</p></section>
<section><h2>The alternatives actually considered</h2><div class="grid"><article class="card"><p class="label">Not chosen for this scope</p><h3>Live queries at page load</h3><p>Reading would depend on a data connection at that time.</p></article><article class="card"><p class="label">Chosen</p><h3>Generated snapshots after review</h3><p>Reviewed content generation is separate from reading.</p></article></div><p class="note">No performance benchmarks, costs, capacity estimates, security audit, or uptime measurements were supplied.</p></section>
<section class="warning"><h2>The accepted cost is staleness.</h2><p>Content can be stale until the next reviewed generation. Ada accepts that tradeoff for this scope. No real-time guarantee is required.</p><p>No automatic refresh job or exact generation time is established by the source.</p></section>
<section><h2>What remains unimplemented</h2><p>No implementation owner, due date, deployment, or verification result was supplied. Decision ownership does not automatically assign implementation work.</p></section>
<section class="card"><h2>Change the decision without erasing its history.</h2><p>A new reviewed record must supersede ADR-007 if the decision changes. Retain the earlier rationale and keep the repository record authoritative.</p><p>Repository URL not supplied. This companion neither edits the record nor deploys the design.</p></section><footer>Fictional worked example by share/artifacts. Names, dates, figures and records are invented for demonstration. Static snapshot; no live data or automatic updates.</footer></main></body></html>

The original worked scenarioThe source scenario, step by step

An accepted snapshot decision with a visible cost

A fictional team's bounded documentation-page decision. It is not a recommendation for other systems.

The original notes

ADR-007, accepted September 7 by technical owner Ada, covers a public documentation reading page. Readers need a daily reviewed summary, not live operational data. Options considered: live queries at page load or generated snapshots after review. Chosen: generated snapshots because the page should remain readable without a live data connection. Consequence: content can be stale until the next reviewed generation. No real-time guarantee is required. Implementation is not yet complete. Any change must use a new reviewed record that supersedes ADR-007; the source record remains in the repository.

Scope

A public documentation reading page requiring a daily reviewed summary, not live operational data.

Decision state

ADR-007 accepted September 7 by Ada. Implementation is not yet complete.

Choice

Generated snapshots rather than live queries at page load, to remain readable without a live data connection.

Accepted cost

Content can be stale until the next reviewed generation; no real-time guarantee is required.

Future change

Use a new reviewed record to supersede ADR-007. Keep the repository record authoritative.

The consequence is part of the decision, not an inconvenient footnote to the chosen approach.

Questions, adaptations & sourcesGo deeper when you need to

Is this the same as meeting notes?

No. An architecture record preserves one significant design choice and its context and consequences, which may span several discussions. Link to supporting notes when authorized rather than substituting a transcript for the decision.

Should an accepted decision be edited when we change our minds?

Follow the team's established process. A superseding record can explain the new context while preserving the earlier rationale. Do not silently erase a decision that others may still rely on.

Can the agent recommend the architecture?

It can help compare supplied options, but this workflow records and explains reviewed evidence and decisions. It must not invent performance or security claims, approve a design, or deploy changes on the strength of a writing request.