Working Tree Is Truth
Handoffs point at files and a decision — not at chat archaeology
The transcript is a diary. The working tree is the fact.
When a coding-agent session ends — Codex, Claude Code, Cursor, same problem — the temptation is to hand someone the chat. “Context is in the thread.” That shifts the cost of understanding onto the next human, who must excavate message 247 for a decision that should have been one line next to the files.
Truth lives in the tree. The handoff points at files and a decision. The chat is optional appendix.
Probe the tree, not the scroll
Before you trust a summary, probe what changed on disk.
Open the paths listed as changed. Run the verify step from the package. Diff against the branch point you care about. You are checking whether the world matches the claim — not whether the agent sounded confident.
If the package and the tree disagree, the tree wins. Update the package or kill the run. Do not reconcile by rereading the argument in the chat.
What a handoff must contain
A handoff is small on purpose.
- Files — paths that changed; the truth surface
- Decision — ship, kill, or one question — one line
- Done when — the acceptance check that was met or missed
- How to verify — command or click path
- Do not dig — transcript is optional context, not the source of truth
If the handoff needs a novel, the outcome was too big or the package was never written. Split or send back.
Link the chat if you want. Do not require it. A reviewer who must read the thread to find the decision does not have a handoff — they have homework.
Why chat archaeology fails
Chats reorder importance by recency. Dead ends and successful paths look the same in a scroll. Tool noise buries the verdict. Tomorrow-you remembers “we fixed auth” and cannot find which commit or whether rollback was named.
The working tree does not care about the plot. It has the bytes. Git history has the sequence. The package has the intent. Together they beat a transcript search.
How to run a probe in practice
Stop the agent before you probe. A moving tree is not a still frame.
Read the package fields first — sixty seconds. Then verify. Then open only the listed files for contradiction. Then write the decision on the package. If you need the chat, open it for a specific question (“what was the error string?”), not for the story arc.
When you pass work to another person or another agent, paste the handoff template filled. Attach diffs or paths. Say where the package lives. Do not say “see thread.”
Where it usually breaks
Summary cosplay: a long agent recap with no file list. Fail it. Demand paths.
Decision in the chat only: “looks good to me” in message 80, nowhere on the PR. Move the decision to the package or it did not happen.
Multi-root confusion: changes outside the listed paths. Either update “what changed” or revert the extras. The tree is truth; the package must match it.
Handoff by vibe: “should be mostly done.” Replace with done-when status and verify result.
A few sharp edges
Probe is not distrust theater. It is cheaper than a twenty-minute reread. You are checking the contract against the bytes.
This is not “never read chats.” Read them when you need a detail. Do not use them as the system of record.
If your team already uses owned asks with receipts — durable goal and outcome outside the harness scroll — the receipt should still name files and decision. A receipt that only restates the prompt is still chat-shaped.
Point the next human at the tree. Leave the diary optional.