When: a session has produced work — decisions, discoveries, rulings, fixes — and some of that has changed what the tree should say, or taught you something the tree does not yet know. Also after a stranger review, a production scan, or any time you look at the tree and suspect it has drifted from what the product actually does.
Built from: re-alignment, saving state for next time, the clean summary.
What to know: sessions are full of detail that never makes it to a block. A ruling you made, a design decision that explains why something works the way it does, a constraint someone hit, a capability that shipped without anyone updating the tree. That detail lives in the transcript and dies when the window closes. Meanwhile, blocks that were true when they were written drift as the product changes underneath them. Both problems have the same fix: walk the session and the tree side by side, find where they disagree, and fix the tree.
The code is the source of truth. When a block and the code disagree, the block is wrong.
- Start from whatever triggered it — a session transcript, an audit report, a review, a scan. Pull out every claim about what the product does, how it works, or what a person can do. Each claim is one line.
- Mine the session for what is worth keeping. Walk the transcript for rulings, decisions, discoveries, constraints, new capabilities — anything that is not already on a block. Each one is a candidate. Step 1 asks "is the tree right?" This step asks "did we learn something the tree does not know yet?"
- For each claim and candidate, find the block it belongs on. Three outcomes: the block exists and agrees (no action), the block exists and disagrees (mark it for correction), or no block covers it (mark it as a gap).
- Walk the other direction. Look at every block the session touched or that the trigger named. Does it say anything that is no longer true? A feature removed, a flow changed, a limit lifted. These are drift.
- For each correction, gap, and candidate, write what the block should say. Corrections are small — change the wrong sentence. Gaps need a decision: does this belong on an existing block, a new block, or nowhere? A block that would rot — one that describes something changing faster than anyone would update it — is not written. The code or the API spec is the record for those. Candidates from step 2 need the same decision: is this a durable fact someone would look for, or a moment that belongs only in the transcript?
- Link session blocks to what they touched. The session block gets edges to the memory blocks it changed, created, or relied on. The reason says what the session did. A future reader following the session finds what it touched; a reader on the memory block finds which session changed it.
- Nothing is written to the tree until you have reviewed it. The proposed changes and new blocks come to you as a numbered list, and you say yes, no, or reword for each item.
A ruling or decision from the session belongs on the block it governs, not on its own block. A ruling with no home block is either a new block or stays in the transcript, and you decide which.
What it produces: a tree that matches what the product actually does, session blocks linked to the blocks they touched, detail from the session that would otherwise be lost, and a list of what you decided not to document so the next reconciliation does not re-raise it.
If you audited the session first: an audit works out what actually happened in the session. Finish it before you change the tree, then use what it found as the trigger for step 1. Without an audit, start from any of the other triggers in step 1.
Author's practice: run this after any session longer than a day, or after shipping a feature. A long session always holds things that were discussed or discovered and never landed on a block.
As a skill: ask the AI to turn this page into a skill that walks the session transcript, finds claims and candidates, compares them to the tree, and produces the numbered list for you to review.