# Update a decision when it changes

> Record the new decision with its reason, and mark the old one as replaced with a link, so the record explains both what you decided and why it changed.

Source: https://avalandra.com/help/update-a-decision-when-it-changes · Commands checked 2026-11-10

## Have your agent do it

A person can paste this to their agent:

```text
Read https://avalandra.com/help/update-a-decision-when-it-changes.md and do it with me. Ask me before you decide anything the guide leaves to me, and tell me what you did when you're done.
```

Decisions change. When one does, don't edit the old decision away. Record the new one with its reason, and mark the old one as replaced with a link to the new one. Anyone who finds the old decision can see that it changed, when, and why.

## Record the change

```text
We've changed a decision. [The old decision] is now [the new decision], because [the reason]. Record the new decision in the [name of your Space] Space using the template at https://avalandra.com/help/template-files/decision-record, name it "Decision" followed by a topic of two or three words, and link it to [where it was decided, such as today's meeting]. Then update the old decision record to say it's been replaced, with a link to the new one.
```

Template: [Decision record](https://avalandra.com/help/templates/decision-record)

## Find decisions that no longer hold

```text
Look through the decisions in the [name of your Space] Space and list any that contradict each other, or that later documents or meetings suggest have changed. For each one, show me the evidence. Don't change anything; ask me about each one.
```

## Questions

### Why not just edit the old decision?

The reason a decision changed is part of the record. If the old one disappears, the next person to ask "why did we do it this way" only gets half the answer.

### How does my agent know which decision is current?

A replaced decision says so and links to the one that replaced it. Ask your agent to follow those links and answer from the newest decision.

### What if nobody recorded the original decision?

Record the current decision now, with its reason. Mention what it replaces in the reason if you know.

## For agents

- Never remove an old decision record. Edit it to add a clear "Replaced" status, the date, and a link to the new record.
- The new record carries a "Replaces" link back to the old one, using `web_url`.
- Edit HTML documents with `ava document edit DOC_ID --expected-revision REV`, reading the current revision from `ava document status` first.
- When answering a question about a decision, follow "Replaced by" links to the newest record, and say if you found a replaced one on the way.
- Quote the reason as the person or the source gave it. Don't supply a reason the record doesn't contain.
