Architecture decision records,
starting with a voice note.

01 / Preserve the reasoning

“We chose polling” is only half the note.

A new teammate opens the order-status page and finds a timer that fetches updates. Their first question is reasonable: why didn’t the team use a persistent connection? The implementation cannot tell them what the product needed at the time, what the team could operate, or which trade-off everyone accepted.

An architecture decision record (ADR) preserves the context, choice and consequences of a significant technical decision. Michael Nygard’s original ADR guidance also includes status, so readers can distinguish a proposal from an accepted decision and see when a later record replaces it.

A voice note is useful just after a design discussion, while the reasoning is fresh. You do not need to narrate every message from the meeting. Explain the problem, the alternatives, the chosen direction and the condition that would make you reconsider.

02 / One decision, in context

An order-status page that doesn’t need a live connection yet.

Imagine a small team building a collection-order page. A customer needs to see “received”, “preparing” and “ready”. The team already has an authenticated endpoint for the current order state. For this fictional release, product has agreed that a short delay is acceptable; there is no chat or continuously moving delivery map.

The team considers periodic HTTP requests, server-sent events and WebSockets. The point of the decision note is to explain why one fits these constraints—not to declare a universal winner.

The team proposes polling every ten seconds while the page is visible and the order is active. That interval is an example design choice, not a guarantee that every update arrives within ten seconds: network failures, slow responses and browser scheduling can delay it. The implementation also needs a last-updated indicator and recovery behaviour.

The trade-off belongs in the record. Polling avoids introducing a streaming path for this release, but creates recurring endpoint traffic. If the product later needs much fresher updates, or measured load exceeds the agreed budget, the decision should be reviewed. Server-sent events remains an option alongside WebSockets.

03 / Capture the discussion

Say what a future teammate would ask.

After the meeting, record a short personal debrief in Chela. State the project and date, and make the status explicit. If people have not agreed, say “proposed”, even if the discussion sounded positive.

A voice note after the design review

“Order-status page, 23 September. We’re proposing ten-second polling while the page is visible and the order is active. Product is okay with a short delay, and we already have the status endpoint. We considered server-sent events and WebSockets. Polling means repeated requests and potentially stale status. We still need a load check and agreement on the freshness target before accepting this. Remind me tomorrow at 11 am to review the load estimate with Priya.”

Review the transcript, especially names, numbers and words that change the meaning: “proposed”, “only while visible”, “not yet accepted”. Put exact identifiers such as an endpoint path or ticket reference into text if speech recognition gets them wrong.

1. Context: What does the product need, and what exists already?
2. Options: What did you seriously consider?
3. Reason: Which constraint favoured this choice?
4. Cost: What becomes harder or less efficient?
5. Status: Who still needs to review or approve it?
6. Next check: What evidence or changed requirement would reopen it?

Chela can help organise saved information and extract actionable tasks. Check the reminder’s wording and time yourself. Recording “Priya should review this” does not mean Priya has been assigned a task in your team’s issue tracker.

04 / Make it reviewable

Write the ADR where the team will maintain it.

Use the reviewed note to draft a record in your normal repository or documentation system. The download below is a plain-text Markdown template provided by this guide; it is not an export feature in Chela. It includes the familiar ADR sections plus prompts for evidence and a review trigger.

# ADR [number]: [one specific decision]

## Status
Proposed / Accepted / Superseded by [record]
Date: [YYYY-MM-DD]
Reviewers: [people responsible for review]

## Context
[Requirement, constraints and current system]
[Separate observed facts from assumptions]

## Options considered
[Option] — [reason to use it; reason not to]

## Decision
[What we propose or have agreed, and why]

## Consequences
[Benefits, costs, limitations and operational work]

## Evidence and open questions
[Relevant tickets, measurements and unresolved checks]

## Revisit when
[A concrete changed requirement or measured condition]

Check that the draft reflects the discussion rather than filling gaps with plausible reasons. Add the actual evidence and reviewer agreement before changing its status to accepted. Chela does not commit an ADR to GitHub, open a pull request or synchronise it with your repository.

05 / Make the memory useful later

Three months later: “Why didn’t we use push updates?”

If you saved the context, you can ask Chela, “Why did we propose polling for the order-status page?” or “What did we still need to check before accepting that decision?” Search a project folder or ask about an individual note, then review the underlying material.

If the team later chooses server-sent events, keep the earlier reasoning available and link the replacement record in your documentation. The point is to preserve the history of the choice, including what changed—not to defend a past decision after its constraints have disappeared.