A thread scratchpad is a short state file for a conversation that matters.
It is not a transcript. It is not a diary. It is not a second copy of the chat.
It answers the questions an operator needs after a restart:
- What is this thread about?
- What did we decide?
- What is next?
- What is blocked?
- What links matter?
- What was last verified?
That tiny file is what lets the assistant resume work instead of asking you to repeat the whole conversation.
Outcome for this lesson
By the end, you will have one active thread scratchpad and a repeatable rule for when to create or update one.
When to create a scratchpad
Create one when a conversation has any of these:
- more than one work session;
- a client or project decision;
- a GitHub Issue or PR;
- a blocker;
- a recurring workflow;
- a correction that should change future behavior;
- a deliverable that needs verification.
Do not create one for every tiny chat. Scratchpads are for conversations that need to survive context loss.
The scratchpad shape
Use this structure:
Use the public copyable version here: AI Brain Thread Scratchpad Template.
What to write in Summary
Bad summary:
Useful summary:
The summary should let a new operator understand the job in ten seconds.
What to write in Decisions
Decisions are the most important part of the scratchpad.
Examples:
This prevents the assistant from re-asking or undoing prior direction.
What to write in Next actions
Next actions should be small and concrete.
Bad:
Useful:
What to write in Last verified state
This is where receipts live.
The point is to make recovery factual, not vibes-based.
Update cadence
Update the scratchpad when:
- a decision changes;
- a PR ships;
- a blocker appears;
- a blocker clears;
- the next action changes;
- the assistant makes a mistake that needs future avoidance;
- a thread goes quiet but will matter later.
Do not update it for every sentence.
Recovery prompt
When a session restarts, ask the assistant to reconstruct state from the scratchpad before asking you questions:
That one instruction turns the scratchpad into an operating primitive.
Lesson checkpoint
You are done when one active project thread has a scratchpad with:
- summary;
- decisions;
- next actions;
- blockers;
- links;
- last verified state;
- do-not-touch constraints.
The next step is to promote one shaped action from that scratchpad into a GitHub Issue.