Here is the workflow as it usually runs. You finish a two-hour session with Claude Code on the token refresh logic, the tests pass, and you do the responsible thing: you keep the transcript. It lands in .prjcontext/sessions/ with a date and a name you will recognise. Then you close the terminal. The step that would turn session into decision record never happens, because it was never a separate step in anyone's head.
Three weeks later a fresh session reads the code, decides the refresh window looks wrong, and proposes the approach you deliberately rejected in that conversation. The transcript is right there in the repository. You do not open it, because scrolling through 3,000 lines to recover one sentence of reasoning costs more than re-deciding on the spot. So you re-decide, slightly differently this time, and the project now carries two half-reasons for one behaviour.
Keeping sessions and writing decisions down get treated as one habit. They are two, and the gap between them is where reasoning disappears. What follows is the missing middle: a short, mechanical pass you run on purpose instead of a vague intention to document things properly.
Keeping the session and writing it down are two different habits
A kept session is evidence. It is complete, unedited and chronological, which makes it excellent for answering "how did we get here?" and poor at answering "what did we settle on?". A decision record is a conclusion. It is short, written after the fact, and organised around what someone needs to know before touching that part of the code.
The two get read at opposite moments. A session transcript gets opened when something is already wrong and you are tracing backwards, which is the workflow in tracing an AI regression back to its root cause. The decision record gets read at the start of work, by you or by an assistant loading context, before anything has broken.
Saving the transcript feels like finishing the job because something was preserved. Nothing was distilled. A repository full of kept sessions and an empty decisions file is a common state, and a misleading one: it looks organised and behaves like no memory at all.
Not every kept session earns an entry
The conversion step only survives if it is cheap, and it stays cheap because most sessions skip it. Before opening anything, ask what the session actually produced.
Worth an entry:
- You chose between two or more real options and the losing option was plausible.
- You rejected something the assistant suggested, for a reason that is not visible in the code.
- You hit a constraint from outside the repository: an API's rate limit behaviour, a library that breaks on your Node version, a platform restriction.
- You accepted a tradeoff knowingly, including "this is slow and that is acceptable for now".
Not worth an entry:
- Implementing a decision that is already recorded. The diff is the record.
- Debugging that ended in a fix with no general lesson.
- Scaffolding, renames, test writing, dependency bumps.
- Exploratory conversations that concluded nothing. Keep them if you want, but there is nothing to extract yet.
Most kept sessions fall in the second list, and that is what keeps the pass from turning into a chore. The companion piece on which AI coding sessions are worth keeping handles the earlier filter, which sessions to save at all.
Turn session into decision record by reading the transcript, not the diff
The tempting shortcut is to open the diff and write the entry from the code. That produces a changelog. The code shows what you did; it almost never shows what you decided against, and the rejected option is the half that stops a decision from being relitigated.
So read the transcript, but not all of it. Three places hold almost everything.
The turn where you said no. Search for your own pushback: "no", "don't", "instead", "that won't work", "we can't because". Your corrections are the densest source of reasoning in any AI coding session, because that is where you had to articulate a constraint the assistant did not know. It is also where you most likely explained something once and never wrote it down.
The last substantive exchange before the implementation run. There is usually a visible hinge: a stretch of back and forth about approach, then a long stretch of edits. The message right before the edits start is often the decision, phrased better than you would phrase it a month later.
Anything the assistant got wrong about the project. If it assumed Postgres and you corrected it to SQLite, that correction is a project fact that was living in your head. Those belong in memory even when they are not decisions, a distinction worked through in project memory for AI coding.
In practice this is five minutes of skimming with a search box, not a careful read.
Write the entry so it stands without the session behind it
The test for a finished entry: delete the transcript, hand the entry to a teammate, and see whether they can act on it. If it only makes sense next to the conversation, you wrote a bookmark.
### 2026-10-09 — Refresh tokens rotate on use, not on a timer
Decision: Issue a new refresh token on every use and revoke the old one.
Why: A fixed 30-day expiry left stolen tokens valid for weeks. Rotation
makes reuse detectable: a second use of a retired token means the chain
is compromised, and we drop the whole family.
Rejected: Short-lived refresh tokens with a sliding window. Simpler, but
it gives no signal that a token was copied.
Consequence: Clients must persist the new refresh token from every
response. Any client that caches the first one will log users out.
Status: Active
Session: sessions/2026-10-09-token-rotation.md
Four things carry the weight: the decision as a statement, the reason, the option you dropped, and the consequence for whoever works here next. The consequence line is the one people skip and the one that prevents the most damage. "Clients must persist the new refresh token" is an instruction an assistant will respect if it reads it and will cheerfully break if it does not.
Keep it short enough that you never negotiate with yourself about writing it. Past about fifteen lines you are summarising the session instead of extracting the decision. The fuller formats in lightweight decision records for AI-assisted projects are worth the effort for architectural choices, not for a weekly pass.
Linking back without making the record depend on the link
The session reference at the bottom is a courtesy, not load-bearing. Write the entry so it still works with the link broken, then add the link for the cases where someone needs the full argument, which is usually a postmortem.
That only holds up if the record and the session age together. A path to a transcript on your old laptop, or a URL into a chat tool's history, breaks quietly and you discover it at the worst moment. Keeping both in the same repository under relative paths is the simple version, and it works with plain folders:
.prjcontext/
memory/decisions.md
sessions/2026-10-09-token-rotation.md
This is the part of the project memory workflow we built PrjLab around. A prj push versions the memory file and the transcript in the same immutable version, so a reference written in October still resolves against the session as it existed then, and a teammate who runs prj clone gets both halves on their machine. They can also open the version in the browser and read the entry next to its session without cloning anything.
Make it five minutes on Friday, not a backlog
This step dies the moment it becomes a project of its own, so attach it to something you already do. Pick one point in the week, run prj status or git status, and look at the sessions you saved since the last pass. For each one, ask whether it produced a real choice. For the one or two that did, open the transcript, search for your own objections, write ten lines into the decisions file, push.
Two rules keep it from accumulating. Do not go back: sessions from two months ago that never got an entry are not a debt, because the decision either survived in the code or stopped mattering. Start from today. And write the entry while the session is recent enough to skim rather than reconstruct, since after a couple of weeks you no longer remember which of your objections was the important one, and the pass turns into archaeology.
If you want the file layout and the push and clone commands in order, the getting-started guide walks through them end to end.
