Document what happened in your session before you and the AI forget

You close a good session and the code is safe. You committed it, which saves a version the project keeps. What isn't safe is everything around it. You lose the approach you tried first and threw out, the reason you threw it out, what the check actually printed and the one thing you meant to do next.

A question you closed and a question you ran out of time on look identical to the next session, because both are simply absent. So it decides the closed one again. It reaches the same fork with none of what you knew, argues it from first principles and lands somewhere near where you landed but not on it. Do that across a few sessions and what you're building is the work of several people who never spoke to each other.

The fix is to stop carrying it yourself. It's two prompts, typed by hand, one at each end of a session. The last thing you run writes down what the session settled, puts the evidence beside each claim, moves the open work to where it now stands and names the one next thing. The first thing you run in the next session reads that back, then runs whatever command tells you the project is still working, the tests or the build or whatever you use.

One line in the opening prompt refuses to call your code up to date until it has gone and asked the shared copy. That reads like paranoia right up until you watch a session spend itself building on a version another machine had already moved past.

The closing prompt writes the only record the next session gets

The recipe at the foot of this page installs a shorter version of both prompts. The ones they are cut from, /end-session and /session-start, do more. The closing one also logs the decisions a session reached and offers to route whatever is sitting in the project's inbox. The opening one also reads the project's stated goal and tells you how many decisions are still waiting on you. What follows is the half worth having on the first day.

The closing prompt is the one that does the work, and it's the easiest to skip, because it runs at the moment you have finished thinking.

It restates what the session did and puts the evidence beside every claim. It shows what the run actually printed rather than reporting that the tests passed. Where there's nothing to point at, it writes the claim as unverified rather than asserting it. That one rule is what makes the record worth reading a week later. A claim with a receipt can be built on. A claim without one has to be earned again, and the note is the only place that difference survives.

Then it moves the open rows to where they now stand, writes the note and commits once.

It writes the note before it commits, so the note never says anything about committing. A line claiming the work was pushed is a prediction made a minute early, and it freezes wrong. Whoever reads it next believes it.

The version here ends on the one next thing. A close-out that reports what happened and leaves you to work out what to do about it has handed the hardest part back at the worst possible moment. The fuller one puts anything needing your decision in a numbered list first, each with a recommendation, and names the next thing after it.

The opening prompt's whole job is to not start working

The opening prompt reads three things after that small file, and then it reports. It reads the board, the one file listing what isn't finished, so it knows what's next. It reads the newest note, so it knows what happened. And it checks the state of your code against the shared copy your machines push to, rather than assuming it, because your machine's idea of what that shared copy holds is a stale note it wrote down last time, and it will cheerfully report everything in sync while another machine is ahead of you.

Then it runs whatever check the project uses, and if that check is already failing before anything has been touched, it says so and that becomes the first job. A broken starting point compounds quietly. Every session after it stacks more work on something that was already failing, and nobody notices until the pile is large.

And then it stops. It's forbidden to write code and forbidden to propose anything. An opening that has already started building has made the one decision that was yours, which is what to build, and it made it from a standing start with less context than you have.

One small file is what makes it a routine instead of two prompts

Both prompts read one small file first, and it holds settings rather than instructions. It names where the board is, where the notes go, what command checks the project and whether the closing prompt may push on its own.

This is the part that compounds. The check you learn the hard way goes in one place, and from then on it runs at the start of every session in that project without you thinking about it again. Add a second project and the prompts don't change at all, only that file does. The prompts stay identical everywhere, which is what lets you stop knowing what's in them.

It's also what stops the prompts rotting. A prompt that hard-codes a path works in the project it was written for and quietly half-works in the next one, reading a board that isn't there and reporting nothing missing.

What you get and what you don't

You get a record of what each session settled with the evidence attached, and a next session that opens by reading it and running your checks. What you don't get is anything that remembers on its own. The next session starts empty however carefully this one ended, and the routine doesn't pretend otherwise. It moves the state into files the project already holds, which is why it works the same in a tool that has no memory at all, and why the note is worth as much to you as it is to the agent.

You also don't get anything that survives being skipped. You type both of these, so both can be skipped, and the opening prompt can only ever read what a closing prompt wrote. A session ended by shutting the terminal hands the next one a stale note and a silent gap it has no way to see. If you're only going to take half of this, take the closing half.

The block below is written for your AI rather than for you. It needs one that can read and write the files in your project, so Claude Code, Codex or Cursor rather than a chat window, and the steps that check your code against the shared copy your machines push to want the project to be a git repository, which is the thing that keeps that history. Paste it in and it asks three questions, uses whatever board and notes you already have instead of replacing them, writes the small settings file, saves both prompts where your tool keeps them, as /session-start and /end-session where that tool has commands, and runs the opening one so you can see what a session will start with. It commits nothing and it lists what it wrote.

Run the closing prompt at the end of your next real working session. That's the one that has to fire first, because the opening prompt has nothing to read until it does.

Paste this into your AI agent or a new chat. The post above says what it does. Some prompts set something up in your project that keeps working after, and others run once, right where you paste them. None of them pushes anything to a remote.

You are installing a two-prompt session routine in my coding project. This needs a tool that can read and write the files in my project, and the steps that check the repository additionally need it to be a git repository. If you cannot do both, say so in one line and stop rather than installing a version of this that I have to run by hand. The goal: when I end a session I run one prompt that writes down what the session settled and what the evidence for it was, and when I start the next one I run another that reads that back and runs whatever checks I have accumulated, so I do not have to remember any of them myself.

Before you read or change anything in my project, including listing the folder, ask me these three things and wait for my answers. Do not look first to make the questions more specific:
1. Which tool I work in: Claude Code, Codex or Cursor.
2. If that tool can read and write my files, which project folder, and is it a git repository? If it is not, offer to run `git init` and explain in one line what that does.
3. What I already have that these should read instead of replacing: a board or task file, a notes or journal folder, and a command that checks the project builds or passes. Any of the three can be nothing.

If I ask what you are about to do before I answer, explain it in plain words and wait.

Then, using my answers:
- Create whichever of these I do not already have. A board at the project root, one table, one row per unfinished item, with the columns Item, State, Order and Notes, seeded with anything I tell you is open. A folder for session notes with a README in it naming the three things a note holds: what happened, what went wrong, what the next session picks up first. Where I already have one of these, use mine and change nothing about its shape.
- Write a file at the project root named session-routine.md holding exactly these four lines and nothing else, each a key, a colon and a value: board: the path to the board file. notes: the path to the notes folder. check: the check command from my answer, or none. push: ask or on-close, defaulting to ask. Write the keys exactly as spelled here, because both prompts look them up by name. Both prompts below read this file first, so when I add a check later I add it here once instead of editing two prompts.
- Save the two prompts below where my tool keeps them. In Claude Code a file at .claude/skills/<name>/SKILL.md, relative to the project root, becomes a command I type as /<name>; name them session-start and end-session, create the folders if they do not exist, and open each file with a short frontmatter block giving name, a one-line description of when to use it written from the goal above, and the line disable-model-invocation: true, so each runs only when I type it. In Codex or Cursor, save both prompts where I can paste them and tell me where. The prompts go in word for word. Everything between the line OPENING PROMPT BEGINS and the line OPENING PROMPT ENDS goes in the first, everything between the line CLOSING PROMPT BEGINS and the line CLOSING PROMPT ENDS goes in the second, neither including its marker lines, and nothing else does apart from the frontmatter block where the tool above called for one. The bullets after the last end line are instructions to you for right now; putting them in a file would make every future run reinstall the routine it is already running.

OPENING PROMPT BEGINS
Orient me, and read nothing that is already in front of you. Read session-routine.md first and use the paths it names for everything below. Read the board. Read the most recent session note, picking it by which file was added last in the project's history rather than by sorting filenames, because several notes can share a date and alphabetical order then hands you the wrong one. Get today's date by running the date command rather than inferring it, and compute any word like today or yesterday from that against the file's own date. Then run git fetch before git status and compare the local branch to its remote, because without the fetch you are reading a cached copy of the remote and it will report in sync whatever the truth is; if the project has no remote, say that plainly instead of claiming it is in sync, and if the branch is behind with nothing of mine uncommitted, fast-forward it and say so. Never merge. Then run the check command session-routine.md names, unless it says none, and if it fails before anything has changed say so and treat fixing it as the first thing. Report briefly and in this order: where things left off, the state of the repository from what git just told you rather than from anything a note claims, the lowest-numbered open row, whether the check passed, and anything you looked for and could not find. Do not write code and do not propose solutions. Orienting is the whole job.
OPENING PROMPT ENDS

CLOSING PROMPT BEGINS
Close out. Read session-routine.md first and use the paths it names. Restate in one short block what was done, what was verified and what remains, and put the evidence next to every claim that something is done or verified: the output of a command that ran this session, a diff, a check that passed. Where you cannot point at evidence from this session, write UNVERIFIED rather than asserting it. Update the board so every row you touched reflects where it stands now, and drop a row that is finished only once its reasoning lives in a note. Get the date by running the date command, then write a session note at the notes path holding what happened, what went wrong including anything you deviated from, and what the next session should pick up first. Do not write whether anything was committed or pushed into that note, because you are writing it before the commit and any such line will be wrong the moment you make one. Then commit everything with a message that says why, in one commit rather than a trailing one for the note. Push only if session-routine.md says on-close, and never force-push. Finish by naming the one thing to pick up next, and then the command to open the next session, alone on the last line.
CLOSING PROMPT ENDS

- Run the opening prompt once, now, and show me its report, so I see what every session will start with. It reads and reports and writes nothing, which is why it is the safe one to demonstrate. If a command saved this session is not available until the next one, follow the saved file by hand and tell me that is what you did, because a run you performed by hand is not proof the command fires.
- Leave everything you created uncommitted and list it for me. Do not commit, do not push to any remote, and do not install software without asking.

Finish by telling me the two commands and when each one fires: the opening one first thing in a session, the closing one last thing. Tell me to run the closing one at the end of my next working session, because the opening one has nothing to read until a close has written something.