Reading wrap, and the bug it found in my own notes
A colleague published wrap, an end-of-session skill for Claude Code. I read it properly, took some ideas, and then found something more useful than any of them.
What it is
Eight files, about 29 KB, no build step, no dependencies beyond jq-or-python3 for its installer. One 7 KB skill file is the whole product — and it is not even the largest file in the repository. That honour goes to the icon.
Its thesis, from the README:
Most session logs are noise. “Shipped v3.57.4” is in git. “CSS is 18KB now” is in the code. The only thing worth persisting is what went wrong and what the user prefers.
Three steps run in order — extract and route, sync, handover — and setup happens as a side effect rather than as a phase. Each extracted fact lands in exactly one home: facts true for anyone who clones the repo go to a committed context file, personal preferences go to local memory, in-progress state goes to the handover and nowhere else.
What it gets right
It states its negative space. A whole section on what it does not record: what shipped, feature descriptions, timelines, anything derivable from reading the code. Most tools of this kind define only the positive list and quietly accrete everything else.
One fact, one home. “Never write the same fact to two homes” is explicit, and enforced when writing rather than by a later cleanup sweep.
The boundary is a file, not a discipline. Committed context travels with git clone; local memory never leaves the machine. A fact cannot leak across, because the two homes have different reach by construction. This is the same trick as putting your secrets in a gitignored file instead of remembering not to commit them.
Deletion is the update. A gotcha fixed during the session gets deleted — never marked [FIXED], never rewritten as “fixed by…”. Append-only knowledge stores grow forever by default; this one has a decay path.
Consume-by-move. The session-start hook prints the handover, then moves the file aside. A stale handover therefore cannot be read twice. That is a state machine, not a convention — much stronger than “check the date before trusting it”.
Exactly one interactive question, ever — whether to install that hook — and a decline is remembered so it never asks again.
Where it breaks
Extraction runs on end-of-session recall. “Review the conversation for gotchas” sees whatever is still in context, so a long session that compacted mid-way silently drops its earliest lessons — the ones furthest from the code, which is to say the most valuable ones. Capturing at the moment of the fix, and letting the wrap-up curate a queue rather than recall a transcript, gets strictly better recall at the same complexity.
No dedup on write. The list grows until it outgrows a page, then splits into an overflow file. That is a size valve, not a redundancy valve — nothing stops the same trap being written three times in three phrasings.
Single-writer assumption. Two sessions in one repository both write the same handover file, and the second run overwrites the backup too. The first handover is then gone entirely. This stops being hypothetical the moment you run agents on more than one machine.
The part worth keeping
I went to check which of its ideas I had already adopted. Three of them sat in a decision note that said, in plain language, “added to the header of X” — and the header of X did not have it. The decision had been made five days earlier. Nothing failed. Nothing warned. The note read as done, so every later session read the rule as live.
A decision note that says “added to X” is an unverified claim about another file.
Deciding and applying are separate acts. Write the target in the same pass, or the note becomes the only place the rule exists.
This is the same failure the skill is built to prevent, one level up. wrap catches lessons that would be lost to a cleared context. What it cannot catch is a lesson that was written down correctly, in a file with no reader and no test — durable, findable, and inert.
One idea I turned down
Deletion-is-the-update, the best single idea in the repo, does not port to my setup. A fixed gotcha’s lesson often outlives its fix: one entry of mine is fully resolved and remains the clearest explanation of why denying a tool in order to force an alternative backfires. The compromise I settled on — delete when the fix removed the failure mode entirely and taught nothing general; keep when the lesson generalises.
Two measured lessons from the same evening, both of which exist because a check disagreed with a plausible story: Whisper picks the wrong GPU and A transcript is not evidence.
Reviewed at v2.0.1, from a fresh clone.