Write the Next-Action Note

Most of the time I lose on a project isn't spent solving hard problems. It's spent remembering where I was.

I sit down, open the editor, and stare at a half-finished change with no memory of what I was thinking when I left it. Which branch. What worked. What I was about to try next. Twenty or thirty minutes gone before I've written a line — paid out just to reload my own context. On a good day that's annoying. On a low-capacity day it's the whole budget, and the work simply doesn't happen.

The fix is small and slightly boring, which is usually how you know it's the right one. Before I stop, I spend the last five minutes writing a note to the next version of me.

Why vague notes fail

The instinct is to leave something like "keep working on the import feature." That note is worthless. It tells future-me the topic, which he already knows, and nothing about the state, which he's forgotten. He still has to reconstruct everything by reading code and guessing. The note saved him nothing.

A useful note isn't a topic. It's a handoff. It assumes the person reading it is tired, has lost the thread, and needs to start moving without thinking first.

What the note contains

Mine has six parts, and I can write it in about a paragraph:

• Current state. What actually works right now. "The CSV parses and the rows land in memory correctly."
• The exact next action. Not the goal — the next physical move. "Map the parsed rows onto the Contact type in import.ts."
• Where it lives. The file, function, or line. Future-me should not have to search for it.
• The known problem. Whatever you already know is wrong or waiting. "Dates come in as strings; they'll need parsing before the insert."
• The decision already made. So you don't re-litigate it at full price tomorrow. "Validation stays on the client, not the server — decided, don't reopen this."
• The done-test. How you'll know the next step worked. "Done when a 10-row file inserts 10 contacts and rejects a bad row with a visible error."

Put together it reads like: The CSV parses and the rows land in memory. Next, map them onto the Contact type in import.ts. Dates arrive as strings and need parsing before the insert. Validation stays on the client — decided, don't reopen. Done when a 10-row file inserts 10 rows and rejects a bad one with a visible error.

That's a note a tired person can act on cold, without a single decision standing between them and the first keystroke.

Where to keep it

I don't overthink this. It goes wherever I'll see it first next time: the top of the file I was in, a comment marked // NEXT:, a line in the project's running notes, or the body of a draft commit. The only rule is that it's the first thing in front of me, not something I have to go find. A note I have to hunt for is a note I'll skip.

The trade

The cost is real: five minutes at the end of a session, usually right when you feel done and want to close the laptop. That's the exact moment the note is most valuable and least appealing to write.

But the math is lopsided. Five minutes tonight, while the context is still in my head and costs nothing to write down, buys back thirty tomorrow, when reconstructing it would cost everything. I don't always feel like paying it. I've never once regretted having paid.

The last five minutes of today belong to tomorrow.