The Handoff Note Every RAXXO Session Ends With

Why an Evenings-and-Weekends Studio Cannot Trust Memory

RAXXO runs across more than a dozen repos, and I work on it in the hours around everything else, not in one continuous stretch. That means the gap between two sessions on the same repo is rarely a single night. It is often three days. Sometimes it is three weeks, if a different tool needed attention first or life got in the way. A studio that ships on a schedule like that cannot rely on memory the way a team working on one thing every day might, where the person who touched a file yesterday is usually the person touching it again tomorrow.

The problem is not that I forget everything. It is that I forget selectively, and never the parts I expect to forget. I remember the feature I was building. I do not remember that I had already ruled out one approach to it, tried a second approach, hit a wall with the second one too, and was halfway into a third when I stopped for the night. Reopening that code three weeks later, I see a partially built third approach sitting next to leftover code from the first two, and nothing in the file tells me which parts are live, which are abandoned, and which I meant to delete but ran out of time.

Git history helps, but only partially. A commit log tells me what changed, not why I chose it or what I already knew did not work. Comments in the code help even less, because comments describe the code as it is, not the decisions that got it there, and a half-finished feature usually has no comments at all, because I was still figuring it out when I stopped.

So a few tools back, after losing an evening to re-discovering a dead end I had already ruled out once, I started closing every session the same way: a short written note, saved next to the work, that exists for exactly one reader. The version of me who opens this repo next, with none of tonight's context left in their head.

What Actually Goes Into the Note

The note stays short on purpose, because a habit that takes ten minutes to do properly is a habit I skip on the nights I am tired, and the nights I am tired are exactly the nights the note matters most. So it answers three questions, and nothing more.

Where did I stop, and why. Not just the last line of code I touched, but the actual state of the thing. Is it working end to end, or does it look complete but fail on one input I have not tested yet. Did I stop because I hit a hard problem, or because it was simply time to close the laptop and the code happens to be mid-thought. Those two situations look identical the next time I open the file, but they call for completely different next steps, so the note has to say which one it is.

What is broken or unverified. Anything I changed but did not fully test gets a line here, plainly. Not "should work" dressed up as done, but an honest "changed this, have not run it against a real case yet." This is the part I am most tempted to skip, because admitting something is shaky feels like leaving loose ends on purpose. But an untested change that looks finished is exactly the trap that costs the most time later, when future-me trusts it and builds on top of it.

What comes next, in order. Not a wish list of everything the tool could eventually use, just the next one or two concrete steps, the ones I would take if I sat back down right now. A long list of future ideas belongs somewhere else entirely. This note is for restarting a specific train of thought, not for planning the whole tool.

I keep the format the same every time, three short questions, so I am not deciding how to write the note while I am also tired and trying to wrap up. A format I have to think about is a format I eventually stop using.

What the Note Buys Me When I Reopen a Repo

The difference shows up the moment I come back to a repo cold. Without a note, the first twenty or thirty minutes go to archaeology, reading code, checking recent commits, trying to reconstruct what state things were actually in before I trust myself to touch anything. With a note, that same twenty minutes turns into two, because the note already answers the question I would otherwise spend that time asking myself.

It also stops a specific mistake I used to make often: quietly re-deciding something I had already decided. Without a written record, an old decision does not feel like a decision anymore. It just feels like an assumption I could reconsider, so I do, and sometimes I land somewhere different than the version of me who already thought it through the first time. Half the time that is wasted effort re-covering the same ground. The other half, worse, I land on the option I had already ruled out for a reason I have now forgotten, and only rediscover the problem with it after building on it again.

There is a compounding effect too, one I did not expect when I started this. Reading back through old notes on a tool, months later, tells me something a changelog never captures: how my judgment on that tool actually evolved, which early instincts held up and which ones I kept walking back. The changelog habit I keep for every RAXXO tool records what shipped and when. The handoff note records the thinking in between, the part that never makes it into a changelog because it is not a finished thing yet, just a train of thought I want the next session to be able to pick back up mid-sentence.

Running more than a dozen repos, the note also does something a single project never needed: it lets me switch between tools without carrying yesterday's context into today's work by accident. How I run a fifteen-repo studio from one CLAUDE.md file covers the structural side of that, the shared conventions that keep every repo speaking the same language. The handoff note is the per-repo layer underneath that structure, the thing that is specific to exactly where one tool was left, not general to how the studio runs.

The One Rule That Makes It Work: Brutal Honesty

None of this works if the note flatters past-me. I learned that the hard way early on, when I wrote a note that said a feature was "basically done, just needs polish," because that is how it felt in the moment, tired and ready to call it a night. Two weeks later I opened the repo, read that note, believed it, and spent an hour polishing a feature that turned out to be maybe sixty percent finished and broken in a way "polish" was never going to fix. The note had not lied exactly. It had rounded up, the way I round up in conversation when I want to feel further along than I am. But future-me read it as fact, because that is what a note on the desk is for.

Since then the rule is simple: the note describes the actual state, not the state I wish it were in, and not the state that makes tonight's session look more productive than it was. If something is half-built, the note says half-built. If I do not know whether a piece works, the note says untested, not working. This matters more than it sounds like it should, because the entire value of the habit rests on trusting the note without re-verifying everything it says. The moment I catch myself softening a note to feel better about stopping early, the habit stops being worth the ten minutes it costs.

The error log I read every morning before anything else works on the same principle from a different angle, an honest record I trust without re-checking, because the moment I stop trusting it, I am back to checking everything by hand and the habit has failed at its one job. A handoff note that oversells progress is worse than no note at all, because a blank file at least tells me honestly that I have no idea where things stand and need to look. A note that lies tells me I know, right up until I discover I do not.

Bottom Line

A note that takes five minutes to write and follows the same three questions every time is a small habit against a real cost: the hours a solo studio loses re-reading old code, re-deciding settled questions, and rebuilding context that already existed in someone's head three weeks ago, just not in writing. The format stays deliberately narrow, where I stopped and why, what is unverified, what comes next, because a format that grows becomes a format I skip on the one night I am too tired to write it properly. And the whole thing rests on one non-negotiable rule: the note has to tell the truth about how far along something really is, even when the truth is less than I would like it to be. A studio built from evenings and weekends does not get the luxury of picking back up exactly where a team working on it every single day would. The least I can do is leave myself an honest map of where I actually left off.