# Scratchpad

> Offloads notes, todos, decisions, and intermediate findings to an external file outside the context window, then pulls only the relevant pieces back when needed — giving the agent persistent memory that survives context limits and resets. Use this skill when the user says "take notes", "keep track of", "remember this for later", or "make a checklist"; when a task is multi-step or spans many tool calls (roughly 20+); when intermediate findings would otherwise be lost; or whenever you're accumulating state that doesn't need to sit live in the context window.

- Skill: `opelpleple/scratchpad` (Agent Skill)
- Install (CLI): `npx skillmds@latest add opelpleple/scratchpad`
- Raw SKILL.md: https://api.skillmd.com/api/skills/opelpleple/scratchpad/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: opelpleple (https://skillmd.com/u/opelpleple)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/opelpleple/scratchpad

---


# Scratchpad

Write working memory to a file instead of carrying it in context — then read back only what the current step needs.

## When to use
- A multi-step task where state accumulates (research findings, a todo list, partial results).
- Long agentic runs with many tool calls, where early findings would scroll out of the window.
- The user asks to "track", "remember", or "take notes" across steps.
- You need durability across a context compaction or a fresh session.

## When NOT to use
- A short, single-shot task — the file is overhead with no payoff.
- Truly ephemeral scratch math that's consumed in the very next step.
- Secrets or sensitive data that shouldn't be written to disk.

## The method (numbered, concrete — the heart)
1. **Create one canonical file.** Pick a stable path and stick to it (e.g. `scratchpad.md` or `NOTES.md` in the working dir). One file the agent always knows where to find.
2. **Structure it for selective reads.** Use clear headed sections — `## Goal`, `## Decisions`, `## Todo`, `## Findings`, `## Open questions`, `## Dead ends` — so you can pull back one section without loading the whole file.
3. **Write as you go, not at the end.** Append a finding the moment you discover it. The point is to get it *out* of context, so don't hoard it in the conversation first.
4. **Record decisions with reasons and timestamps.** "Chose X over Y because Z" — future reads (and a future you) need the rationale, not just the verdict.
5. **Keep a live todo with status.** Mark items `[ ]` / `[x]` / `[blocked]`. This is the agent's task ledger; update it after each step.
6. **Log dead ends.** Write down what didn't work and why, so neither you nor a successor repeats it.
7. **Read back surgically.** When you need state, read the relevant section — not the entire file. Treat the file as a database you query, not a blob you reload.
8. **Reconcile before finishing.** At the end (or before a handoff/compaction), make sure the file reflects final reality, then it doubles as your summary source.

## What good looks like
- At any moment you could lose the conversation and reconstruct the task from the file.
- The file is the source of truth for todos and decisions; the conversation just acts on it.
- Reads are targeted (one section), keeping live context lean.
- Dead ends and rationales are captured, so the same mistake never gets made twice.

## Anti-patterns
- **Notes that never leave context** — narrating findings in chat but never writing them, so they vanish on compaction.
- **Many scattered files** — losing track of where state lives; keep it canonical.
- **Reloading the whole file every step** — re-bloating the window you were trying to protect.
- **Write-only scratchpad** — recording but never reading back, so the notes do no work.
- **Stale ledger** — a todo list that no longer matches reality, which is worse than none.

## Example (short, vivid)
A migration touching 40 files. Instead of holding progress in context:

```markdown
# scratchpad.md
## Goal: migrate all API routes from v1 → v2 auth middleware
## Todo
- [x] users.ts
- [x] orders.ts
- [blocked] billing.ts  — uses removed `legacyToken`; need product decision
- [ ] 37 remaining (see grep results below)
## Decisions
- 2026-06-28: keep v1 shim for `/webhook/*` (third parties pin old format)
## Dead ends
- Codemod via regex broke template strings — doing AST-based pass instead
```
The agent appends after each file, reads only `## Todo` to pick the next one, and the run survives any reset.