pauldalton.ai2026-07⏺Read ~/paul/writing/2026-07-the-docs-are-the-memory.md
The docs are the memory
2026-07 · Paul Dalton
A build that takes a week doesn't fit in a session. The context fills, you open a new one, and everything the agent knew is gone: what you decided, what it already did, what "done" was supposed to mean.
The obvious fix is to re-explain. That's the expensive one. Every retelling is a slightly different plan, and the drift compounds — you end up building something nobody designed, assembled out of four partial recollections.
The alternative is to stop treating the plan as conversation. Make it a file, before it's code.
Four files, written before anything runs
The moment the agent finishes describing a plan — and before it touches anything — it writes:
⏺Write BUILD_[plan].md
⏺Write PROGRESS_[plan].md
⏺Write CHECKLIST_[plan].md
⏺Write PLAYBOOK_[plan].md
They do different jobs, and the split matters more than the contents.
BUILD is the spec
Every phase. Every file that gets created, modified, or deleted, by name. The pattern for each change, the gotchas, and the command that proves it worked.
Naming files is the part people skip, and it's the part that pays. "Convert the invoice components" is a sentence you can nod along to. A list of eleven filenames is a thing you can count.
PROGRESS is a state machine
One table per phase, one row per file, and one line that matters more than the rest of the document:
>>> RESUME HERE <<<
Phase 2, Step 3: convert the invoice table
Exactly once, in the whole file. A new session opens PROGRESS, finds that marker, and knows where it is without asking you.
Two rules that look fussy and aren't:
Every file gets its own row. Never group them. A row that says "convert the
invoice components" has no honest status. It's half done for most of its life,
and half done reads as [~] forever. Eleven rows are either [x] or they're
not.
The marker exists exactly once. Two markers is two answers to the only question the file is there to answer.
CHECKLIST is what "done" means
Gates per phase. Exact commands — the bash, the grep, the SQL — plus the output you should see. Not "confirm the migration worked."
Nothing gets marked complete in PROGRESS until its gate passes in CHECKLIST. That's the whole point of them being two files: the thing that claims progress isn't the thing that verifies it.
Expected output goes in the file for the same reason as everything else here — a session with no context has to be able to run the check and know whether it passed.
PLAYBOOK is for you
The other three are for the agent. This one's for the human: the prompts you paste to start a phase, recover a lost session, or slow it down when it's running ahead of you. A specific kickoff prompt per phase, not a generic one.
It exists because the failure mode isn't the agent forgetting. It's you, at 9pm, trying to remember how you started Phase 3.
Then don't trust the scaffold
The scaffold was written by the same model that's about to execute it, from a plan that only existed in conversation. It will have gaps.
So the second prompt audits it: every action in the original plan against BUILD, every file in BUILD against a row in PROGRESS, every phase against a gate in CHECKLIST. Findings in a table, then fixes. Still no code.
And don't trust "complete"
The third prompt opens with the only sentence that matters:
Full build is allegedly complete.
Then it checks: every file BUILD claims exists, every step marked [x], every
gate rerun, the full E2E flow, a project-wide typecheck, and a sweep for
orphaned imports and dead references left behind.
If anything fails it reports and stops. It doesn't fix. You decide.
None of this makes the agent smarter. It makes the build survive the agent forgetting — which, on anything longer than an afternoon, is the constraint that actually binds.
The three prompts are here, in order: Plan scaffold workflow.
next: all writing · rss · back to the session ↺