A decision the next session never saw

An architectural call made in a meeting, or in one engineer's agent session, often never reaches the next person or the next tool. Public threads show how teams try to keep a shared decision log, and why a missing or stale record still sends agents the wrong way.

·6 min read

Public developer discussions often come back to the same gap. An architectural decision is made in a meeting, or in one engineer's Claude Code session. Weeks later, another engineer's agent changes the code in the opposite direction. Oana Olteanu asked whether this was already causing rework or bugs, and what teams use today: repo rules, shared memory, code review, or something they built themselves.

Nobody was asking for a longer instruction file. They wanted a place for the decision that the next session would actually read.

A decision that never left the session

Iván Spiler wrote that he hits this constantly in daily work with his own agent setup. The agents are not the hard part. A decision made in one session simply does not exist for the next one. Their fix is a shared decision log: every agent reads it before starting, and appends to it when done. He called it crude. He also said it kills most conflicts.

blackleg described the same pattern when two people run agents on the same repository for more than a couple of days. Notes from the first session never reach the second session's context. Quiet contradictions only show up in review. A short AGENTS.md that every session has to read first cut the surprise rewrites, but verbal decisions from meetings still slipped through. The open question was how to capture those before they reach the agents.

This is not a new problem, only a faster one. Microsoft's Azure Well-Architected guidance on architecture decision records says it directly: a decision that is made but never recorded will likely be forgotten. The same debates come back, or later changes quietly contradict the original intent.

Writing it down is not the same as keeping it current

Some teams already keep a shared place for architecture. The hard part is keeping it updated.

Ryan keeps an architecture repository that developers and agents can both pull down and reference. The hard part, he wrote, is discipline. If it goes stale, the agents will be back to moving in the wrong direction.

That warning is older than coding agents. In 2011, Michael Nygard published Documenting Architecture Decisions. Large documents, he argued, are never kept up to date, and nobody reads them either. Small, modular records at least have a chance of being updated. The motivation behind a decision is one of the hardest things to track over the life of a project. Without it, a later developer has only two bad options: accept the decision blindly, or change it blindly. His early experience report was modest. The format had been in use since early August of that year, on a few projects, with six to ten developers rotating through. The feedback was positive, especially for longer-term intentions. It was not a large controlled study.

AWS Prescriptive Guidance on the architectural decision record process takes the same view of history. Once the team accepts an ADR, it becomes immutable. If new insights require a different decision, the team proposes a new ADR. When the new one is accepted, it supersedes the previous record. Microsoft's guidance calls the log append-only:1 do not go back and edit accepted records. Write a new record, mark it as superseding the old one, and link the two. A record without justification, it adds, loses its value over time, because later readers cannot tell whether the decision still applies.

A decision log that can be silently rewritten is a log you cannot trust. A decision log that is never updated will point the next agent the wrong way.

Some decisions can be checked. The rest wait until review.

Vini Francisco described a practice that is working for his team. They keep ADRs in the repository, with the decision, the why, and the alternatives they ruled out. Agents read them before touching the code. The decisions that can be checked become lint rules that enforce the architecture, such as which module may import from which. Then the agent cannot contradict them: CI blocks it. He was clear about the limit. There is still no good way to catch the rest before review.

That split is useful. Import boundaries can be linted. The reason you rejected an alternative usually cannot. Code review can still catch a contradiction, but only after the work is done. The next session needs the current decision, and the rationale, before it starts.

Antonio Torres, an engineering manager at Amazon, wrote that his team began with steering files in the repository, such as architecture.md, security.md, and testing.md. They are also moving to spec-driven development, with the specs in the repos. On his team, he asks every engineer to turn on meeting summaries, so there is a written record of what they discussed. That is one concrete way to catch verbal decisions. A meeting that leaves nothing written down will not be visible to the next agent.

These are public posts, not a survey, and they do not measure hours of rework. They do describe the same failure from several sides: the decision was made, and the next session never saw it; or it was written down, and then it went stale; or only the checkable part could be enforced before review.

Give the next session a current answer, and a trail

A practical split looks like this.

  • Put the decision where the next session will actually read it. Keep it in the repository, with the project, not only in a chat or a meeting. Have the agent read it before it starts work, and append to it when a decision settles.
  • Write the why, and the alternatives you ruled out, not only the choice. A later reader, human or agent, needs those to know whether the decision still holds.
  • Capture verbal decisions before they reach an agent. If it was decided in a meeting, write it down in the same log. A short instruction file cannot hold every spoken call, and should not try to.
  • Do not silently edit an accepted record. If the decision changes, write a new record, mark the old one superseded, and link the two. The current answer can be rewritten as a whole. The trail of how you got there stays append-only.
  • Turn checkable constraints into lint or CI. Leave the rest as current truth that the next agent must read. Review will still have to catch what a linter cannot see. That is expected.
  • Watch for staleness. If the shared architecture notes are out of date, agents will follow them anyway, and move in the wrong direction.

The useful shape is a current answer that can be rewritten when the truth changes, plus an append-only trail of how you got there. The next session should load the current answer. The trail is where reversals, meeting notes, and the rejected alternatives belong.

MindMux builds this kind of record. Here is what it does today.

MindMux captures background, decisions, and constraints from the conversations you already have with agents, and writes them into a Markdown project brain. Agents read that brain over MCP before they start a task. To connect Claude Code or Codex, install @mindmux/cli and run mmx setup in the project. mmx setup --local gives a local Brain without Cloud login. The open, local counterpart, brain.md, is a brain/ folder in your repo plus a small CLI (@mindmux/brain-md). Every page keeps a compiled_truth, the current answer, and an append-only timeline of how you got there. It is git-native and agent-agnostic: Claude Code, Codex, Cursor, and anything else that can read a file.

This is cross-session, cross-tool decision memory.

If a decision made yesterday already shows up in the next session, on the next tool, it is working.

Footnotes

  1. Microsoft, Maintain an architecture decision record (ADR), Azure Well-Architected Framework. ↩

Share to