xoai Decision logs
The file system is the source of truth for state — what exists in
.sage/work/ and its frontmatter. Decision logs are the source of truth for
reasoning. A diff shows what changed; only the log shows why, and why is the
thing that is gone in three months.
Which log
| Decision | Goes to |
|---|---|
| Anything scoped to one initiative | .sage/work/<initiative>/decisions.md |
| Cross-initiative: constitution choices, conventions, project-wide calls | .sage/decisions.md (global) |
Default to the initiative log. The global file is for decisions that outlive the work that produced them.
Why the split exists
Two parallel initiative branches, both prepending to one global file, is a guaranteed merge conflict — on every checkpoint, forever. The per-initiative split is what makes parallel sessions safe, and it is the entire reason for the rule.
Writers switch immediately, including for initiatives already in flight. Readers check the initiative log first and fall back to the global one, so the switch is safe mid-cycle and needs no migration.
How to write an entry
Prepend — insert directly after the # Decisions header, before existing
entries. Newest first. A log you have to scroll to the bottom of to find the
current state is a log nobody reads.
Each entry records:
- What was decided
- Why — the reasoning, not the restatement
- What alternatives were considered, and why they lost
The third one is what makes a decision log worth keeping. "We chose Postgres" is a fact you could have got from the lockfile. "We chose Postgres over DynamoDB because the access patterns are relational and we would have spent the savings on a join layer" is a decision, and it is the thing that stops someone relitigating it next quarter with the same arguments and less context.
When
At every checkpoint that involved a decision. The compliance signal is
observable: after a checkpoint with a decision in it, the initiative's
decisions.md has a new entry at the top.
Not "at the end". At the end you will remember the conclusion and not the alternatives, and the alternatives are the part with the value.
Archive rotation
When the global decisions.md passes ~200 lines, at the next workflow
close: keep the 20 most recent entries, move the rest to
decisions-{YYYY-MM-DD}.md. Archives are read-only reference.
Initiative logs live and die with their work directory. No rotation.