April 24, 2026 | Agent Grounding

Decisions You Do Not Have to Relitigate: ADRs in the Agent Loop

Key Takeaways

  • An ADR captures context, decision, alternatives considered, and consequences. The full reasoning, not just the outcome.
  • ADRs are sequentially numbered, immutable once written, and superseded (not edited) when later decisions overrule them.
  • The brain exposes a `record_adr` MCP tool that lets any agent session create a new ADR inline as the decision is being made.
  • Stored in the vault, indexed for retrieval, surfaced via `memory_search` and `memory_ask` when a similar question comes up again.
  • The compound effect: the team stops relitigating the same trade-offs. The reasoning behind every architectural call is always one query away.

Most teams record decisions and lose the reasoning. The outcome lands somewhere (a Slack pin, a Confluence page, a comment on a Jira ticket) and the why evaporates within weeks. Six months later, somebody asks "should we use Approach A here?", the team relitigates the same trade-offs from scratch, and arrives at roughly the same answer two days late.

The fix is structural. Capture the reasoning, not just the outcome. Make it queryable. Architecture Decision Records (ADRs) have been a known pattern for years. The thing that makes them work in practice in 2026 is wiring them into the agent loop so they get captured at the moment the decision is made, not weeks later when somebody "gets around to writing it up".

Why outcomes-only loses

The pattern teams default to is "decide, document the outcome, move on". The problem is that outcomes alone are unhelpful when the decision needs to be revisited. Six months later, somebody looks at "we use Approach A" and wants to know:

  • Did we consider Approach B and reject it? Why?
  • What were the trade-offs at the time?
  • What constraints drove the call (a deadline, a vendor relationship, a team skill gap)?
  • Have those constraints changed?

Without the reasoning, the team has no way to assess whether the old decision still applies. They re-do the analysis from scratch. Often they reach the same conclusion. Sometimes they reach a different one for the wrong reasons (the original constraints have not actually changed, but the new analysis missed them).

ADRs prevent both failure modes by recording the reasoning alongside the outcome.

The ADR shape

An ADR has a small number of fields. Resist the temptation to add more.

  • Number: sequential, never reused. Our most recent ADR is in the 30s.
  • Title: a one-line description of the decision.
  • Status: proposed, accepted, deprecated, superseded.
  • Context: what was happening that forced a decision. Constraints, deadlines, prior calls, the trigger.
  • Decision: what we chose to do.
  • Alternatives considered: the options we did not pick, with one or two sentences each on why not.
  • Consequences: what we accept by making this call. The trade-offs we are knowingly taking.

That is it. Seven fields. Most ADRs fit on a single page. The constraint to be brief is what makes them readable months later.

The capture rule

ADRs only work if they get written at the moment of the decision. A team that says "we will write up the ADR later" reliably does not. The moment passes, the context drains out of memory, the writeup never happens, and the team is back to outcomes-only.

The rule we run is mechanical: the ADR gets written before the decision lands in code. If the team is about to merge a PR that embodies a non-trivial architectural call, the ADR comes first. If the team is about to commit to a vendor, the ADR comes first. If the team is about to deprecate a piece of infrastructure, the ADR comes first.

The friction has to be tiny for this to hold. Seven fields, ten minutes maximum. Anything heavier and the rule erodes within a quarter.

The MCP tool that makes it stick

The brain exposes a record_adr MCP tool. Any agent session can call it with the seven fields filled in (often the agent fills them in from the conversation context with one prompt to the user to confirm). The brain assigns the next sequential number, writes the file to decisions/, indexes it for retrieval, and returns the ADR's hash reference.

The whole capture loop takes a single tool call. The agent does not need a separate workflow, the developer does not need to switch tools, the ADR is part of the conversation that produced the decision.

The result is that ADRs actually get written. Friction was killing the practice on most teams. Putting the capture inside the agent loop removes the friction and the practice survives.

Retrieval as the payoff

Once captured, ADRs feed the brain's normal retrieval. A future query like "should we use approach A here" surfaces the ADR that picked approach A originally, with its full reasoning. The agent (or the human) reads the context, the alternatives considered, the consequences. They can then answer two questions cleanly:

  1. Has any of the original context changed?
  2. Were there alternatives we now think we should reconsider?

If the answer to both is no, the original decision stands. The conversation is over in minutes, not days. If the answer to either is yes, the team writes a new ADR that supersedes the old one (status: superseded, with a reference to the new ADR's number). Both records remain searchable. The history of the team's thinking is intact.

What this looks like in practice

We run this pattern across Dendro Logic and one contract engineering team. Counts as of late April 2026:

  • ADR-0016: MCP-first brain access (decided April 2026).
  • ADR-0017: Structured session capture (April 2026).
  • ADR-0018: Secrets never in git (May 2026).

Plus several smaller decisions covering tier-routing, scope boundaries, and the LLM-tier convention. The compounding effect is visible: when a similar question comes up in a session three weeks later, the agent surfaces the relevant ADR before the developer has finished asking the question.

The qualitative shift is from "we are about to repeat a discussion we already had" to "we already decided this, and the reasoning is here". The latter saves hours every time it kicks in.

When ADRs are wrong

ADRs are for non-trivial architectural decisions. They are wrong for:

  • Implementation details that are not architecturally significant (which library to use for date parsing, how to format an error message).
  • Decisions that are reversible with no migration cost (most cosmetic UI choices).
  • Speculation that has not actually become a decision yet (write a design doc instead, promote to ADR when the team commits).

A team that ADRs everything ends up with 200 ADRs nobody can navigate. A team that ADRs only the genuinely consequential decisions ends up with 30 records that pay for themselves every time one gets retrieved.

Take the Next Step

If your team has been relitigating the same decisions every quarter, and the reasoning behind each call keeps evaporating, the answer is structural. We help teams stand up the ADR pattern, instrument the record_adr MCP tool, and wire retrieval so future sessions actually see the prior reasoning. Get in touch if you want a fresh pair of eyes on yours.