Scratchpads

Scratchpads and memory serve different purposes. Memory (via CLAUDE.md) is persistent knowledge about your project—patterns, conventions, and decisions that last across sessions. Scratchpads are session-bounded working memory for a single task. Use a scratchpad when you're tracking complex state, debugging something that spans hours, or handing off work to a future session.

When to Use Scratchpads

Reach for a scratchpad when:

• You're working on something multi-day and need to capture intermediate state before your session compacts.
• You're debugging a flaky test or race condition and need to preserve failure logs, hypotheses, and what you've already tried.
• You're refactoring a large module and need to track which parts are done, what depends on what, and what's broken.
• You're handing off to a teammate or to yourself tomorrow and want a precise snapshot of where you stopped.

The moment when you actually need one: You're three hours into debugging a flaky test. You've found clues pointing to two possible causes, but the test passes on re-run and you lose your train of thought. Before your session ends or compacts, a scratchpad lets you write down "hypothesis A (thread race on cache invalidation), hypothesis B (timing dependency in test setup), next step: run with sleep(100) after connection pool init to isolate."

Creating and Maintaining Scratchpads

Ask Claude to create a scratchpad for your task:

> Create a scratchpad to track state on the payment integration. 
> Include current blockers, what we've tried, and what's next.

Claude will create a markdown file in .agents/scratchpads/ and maintain it as you work. The scratchpad becomes a working document: decisions get logged, failed approaches get marked, and the next session can resume exactly where you left off.

File scratchpads are stored in your project repository (version controlled, shared with teammates) or kept private in your user-level scratchpads directory.

Resuming After a Break

After /clear or in a new session, reference your scratchpad:

> Continue with the payment integration. 
> Reference: .agents/scratchpads/payment-integration.md

Attach the file or mention it directly. Claude reads the scratchpad, understands what was done and what's pending, and picks up where you left off.

Example: Real Debug Scenario

# Debug Session - Flaky Cache Test - 2026-04-29

## Problem
test_cache_expiration() passes 7/10 runs, fails randomly on CI

## Hypotheses
- **Thread race**: Cache invalidation runs before read completes
  - Evidence: test_debug.log shows "InvalidateCache called while Read in progress"
  - Tried: Added RWMutex, test still flaky
  - Status: Unlikely but not ruled out
  
- **Timing dependency**: Test clock manipulation interferes with real timers
  - Evidence: Test mocks time.Now but setTimeout still uses wall clock
  - Tried: Nothing yet
  - Status: Most likely

## Next Steps
1. Run with sleep(100ms) after connection init to isolate timing
2. Add detailed logging to cache.go (line 47+)
3. Re-run 20x to confirm pattern

This scratchpad becomes your resume point. Without it, you start the next session cold.

Related

• Memory - Long-term project knowledge via CLAUDE.md
• Context - Optimizing conversation efficiency