Plans Die in Chat History. Put Them in the Repo.

Last week I went looking for a feature design I had approved in August. It was gone: not misplaced, deleted, along with two other plans my own notes still pointed to.

Where the plans lived

I plan every bigger change with an AI coding agent. We agree a plan in the chat, I approve it, and the agent builds against it. Claude Code keeps those plans in ~/.claude/plans, and my notes linked straight to them.

That folder is a cache, not storage. It gets cleaned up on roughly a 30-day cycle: on 1 October it held nothing older than 12 September. Nothing warns you before a plan goes.

With an agent doing the building, the plan is the spec. One of the lost ones held the whole design for the bug-fixing loop in my app: report a bug from inside the app, let an agent fix it, and show the result in a notifications panel. I searched the repo for it and found nothing, because it had never been there.

What survived, and why

Some of it survived. The autonomy decisions made it, because I had written them down twice: bugs are fixed and pushed by the agent, ideas go to a backlog I pick from by hand, and a dry-run week is mandatory before any of it runs for real.

A few design elements survived as names without their reasons: a narrower write scope for the fix agent, a snapshot to undo a bad fix, a build gate run by plain code, a cap on the size of a diff. The numbers didn't survive. Nothing records what that diff cap was set to.

So the plan in the repo is now a reconstruction, and it says so at the top, in three tiers: settled, named, lost. Inferring the lost half would be worse than the gap.

The rule

An approved plan, and any newly locked decision about how the system works, lands in the repo in its first commit. Not at the end of the feature. First, before a single line of code is written against it.

• The plan, verbatim, in a dated file in the repo, with a header naming the chat-side original it was copied from, so anyone can tell a copy from a rewrite.
• A reconstructed plan says so at the top, and keeps what's settled apart from what's lost.
• Decisions get their own file, one row each, separate from any plan, because a plan is finished when the feature ships and a decision isn't.
• The survivors moved in with the rule. The three plans still on disk that were about this system went into the repo verbatim.

A decisions file, with the why and the where

Plans describe work; decisions outlive it. So there's one more file: the standing decisions about how the system is built and run. It started with nine rows.

Two of the first rows: commits go straight to main, because in a one-person repo a branch adds a merge step and buys nothing a revert doesn't. And the AI proposes; it never creates the goals at the top of my system on its own.

Every enforcement point was checked against the code the day the file was written. That's what the "where" column is for: a decision you can verify, not a sentence nobody checks.

The cleanup exposed one more gap. A session opened inside the repo was reading no memory at all, because all 26 of my notes were keyed to the parent folder. If you rely on per-project memory, check which folder it actually belongs to.

What I'd tell a team

• Treat chat history as a scratchpad. Anything that only lives there is gone in a month, whatever tool you use.
• Commit the plan before the code. If an agent builds from a plan, the plan belongs next to the code it produced, where review and git blame can find it.
• Write down the why and the where. The what is already in the code. The reason and the enforcement point are the parts that evaporate.
• When something is lost, say so. A labelled gap is honest. A confident reconstruction is a new, unreviewed design wearing an old plan's name.

An approved plan that lives only in a cache has a deletion date, not a home.

From the file that replaced the lost plan

If it isn't in the repo, it's a draft with an expiry date.