The first time I used my decision ledger, in June, it found two forks in the session, two choices between alternatives. One of them never came up in the conversation. The model had set the locale to en-CA (Canadian English) on its own.
That is the kind of entry I value most. I can’t log a decision I never knew was made.
Once agents take part in the work, knowing who made which call is no longer a nice-to-have. In my portfolio post, I mentioned the decision ledger behind the site, and a reader asked me to share the parts that can be reused elsewhere. This is the first of them, and the commands are on GitHub.
Sessions forget, and the reason is lost first
A month later, I rarely need to know what was decided. I need to know why.
At the end of a session, my slash command /sum reviews it and writes one entry per real fork, a choice between named alternatives. In Claude Code, it appends them to the project’s decisions.md itself. In a chat, the model has no disk, so /sum hands me a file, and /land appends it in Claude Code without rewording anything. At the start of the next session, /resume reads the latest entries back to me.
Other tools ask the model to list its assumptions before it starts. The forks I care about show up in the middle of the work, so my ledger is written afterward, over the whole session. The cost is that I learn about a silent decision only after it is made.
An old practice with a new writer
My format started as a lighter version of the architecture decision records engineers keep. The idea is older than that. Researchers of design rationale have documented the reasoning behind decisions since the 1970s, and in 1994, Jonathan Grudin identified why software for groups often fails. The person who does the work is rarely the person who benefits.
With a model in the session, that cost is gone for me, because the model writes the record. The risk moves. A record written by the model can put a reason in my mouth.
The model writes the record. It must not invent my reasons
If the model decided, it writes its own account of why, every time. If I decided and said why, it writes down what I said and adds nothing. If I decided and said nothing, the field stays empty. Repeating my choice back to me doesn’t count as a reason.
An empty Why still says something. I made the call, and the reason exists only in my head. /resume lists the empty fields at the start of each session, and they wait for me.
A decision record expects a justification in every entry. Mine says whose reason it is and leaves it empty when nobody gave one. Before publishing, I had the model look for that rule in published practice, and in what it read, it found none. I have not read those sources myself.
The model’s label is on three of every four entries
The two ledgers behind the site and its design system cover the period from August 2, the date of their first entry, to October 3. In them, 1,783 of 2,360 entries are marked as the model’s call. Of the other 577, 277 still have no reason written down.
The count weighs every fork the same. A locale or a default counts as much as a design decision.
I would rather have an empty field than a plausible reason I never gave. The cost is a queue only I can clear, and I am behind on it.
An empty field meant two things
The first version said, “when in doubt, leave blank.” So an empty field could mean I had decided without explaining, or that the model couldn’t tell who decided. By September, nine fields sat empty in the design system’s ledger. Going through them, one turned out to be the model’s own decision. The model sent one of my answers back because it only repeated the choice.
The model proposed a separate label for unclear authorship. I refused. There must always be an author. Now, if the model can’t tell who decided, it asks before it writes.
A yes to a recommendation looked like my own idea
The second break showed up while I was preparing this post. The ledger recorded who decided. It did not record that the model had recommended the option I took. I said yes, and the entry showed my decision with an empty reason. The model’s part in it was gone.
Madeleine Clare Elish has a name for where that leads, the moral crumple zone, where a human carries the responsibility for what an automated system shaped.
From now on, an entry where the model recommended an option carries that recommendation and the argument as it was given at the time. It also shows when I chose against it.
The model proposed three ways to record a recommendation and recommended one of them. I said yes. That entry carries the line it introduced, and its Why is empty.
The model’s own reason is testimony
Research on how models explain themselves shows that their stated reasons can leave out what actually drove the answer. So I read Why (model) as testimony. It is the model’s account of itself, and nothing in the ledger checks it.
The entry format, after two repairs
**S<N>-K. <short title>**
- Context: <what the fork was>
- Options: <A / B (/ C)>
- Recommended (model): <its recommendation and argument, if it gave one before I chose>
- Decision: <what was chosen>
- Why (model): <its own account> the model decided
- Why (context): <what I said> I decided and said why
- Why: I decided and said nothing
- Rule: <the project standard behind it, or "none">
If you reuse one part, reuse the empty field.
GitHubsacredvalentin/