Scratchpad and Task Tracking Patterns

The scratchpad as working memory

Previous lessons established CLAUDE.md as persistent memory information that survives across sessions. Scratchpads are different: they are working memory during active tasks. CLAUDE.md stores what the agent should always know. Scratchpads store what the agent needs to know right now.

This distinction shapes how context gets used. CLAUDE.md content loads every session, competing for attention in the context window. Scratchpad content exists only when relevant created during work and cleaned up after. Loading a 200-line project plan into every session wastes context on information irrelevant to most tasks. Creating that plan in a scratchpad file makes it available when needed without polluting unrelated sessions.

What counts as a scratchpad

A scratchpad is any temporary file used for agent working memory. Unlike CLAUDE.md, nothing loads automatically the agent reads scratchpad content when directed or when it decides the information is relevant.

Common scratchpad implementations:

Dedicated file: SCRATCHPAD.md or scratch.md at project root
Directory-based: .claude/scratchpad/ with multiple working files
Task-specific: branch-analysis.md or refactor-plan.md named for the current work
Session-isolated: Claude Code has a session-specific scratchpad directory isolated from the project

The format matters less than the discipline: use files for working memory rather than relying on conversation context to hold everything.

Task tracking with markdown checklists

Markdown checklists give you lightweight task tracking that agents read and update:

## Authentication Migration

### Completed
- [x] Audit existing auth endpoints
- [x] Design new token structure
- [x] Create database migration

### In Progress
- [ ] Implement refresh token rotation
  - [x] Token generation logic
  - [ ] Storage layer (blocked on security review)
  - [ ] API endpoint

### Remaining
- [ ] Update client SDK
- [ ] Integration tests
- [ ] Documentation

This format does several things at once. The agent reads current state immediately rather than inferring from conversation history. Checked items show completed work without recounting it. Nested items add granularity without separate tracking systems.

Why checklists beat conversation tracking

Consider a 30-turn conversation about a multi-step refactoring. By turn 25, the original task list exists only in summarized form, if at all. Context compaction may have reduced "implement five validation rules" to "validation work in progress." The agent loses track of which rules are done.

A checklist file fixes this. Each completed item gets checked explicitly. The agent reads current state at any turn, regardless of how much conversation preceded it. Progress survives compaction, session resets, and even conversation-only rewinds.

Updating checklists

Agents should update checklists immediately after completing items, not in batches:

<!-- Before working on storage layer -->
- [ ] Storage layer (blocked on security review)

<!-- After completing storage layer -->
- [x] Storage layer (security review approved, Redis selected)

The annotation captures context that a simple checkmark loses. "Storage layer complete" tells the next session (or next agent) less than "Storage layer complete security approved Redis over PostgreSQL sessions."

The todo.md pattern

Beyond simple checklists, dedicated task files structure larger efforts:

## Feature: User Dashboard

### Objective
Add dashboard showing user activity metrics.
Target: 2026-01-20

### Requirements
- Display last 30 days of login activity
- Show storage usage with visual breakdown
- Include export to CSV
- Mobile-responsive layout

### Tasks
1. [x] Create Dashboard component shell
2. [x] Implement activity metrics API endpoint
3. [ ] Build activity chart component
4. [ ] Add storage usage visualization
5. [ ] Implement CSV export
6. [ ] Mobile breakpoints and testing

### Notes
- Using Recharts for visualizations (team standard)
- Activity data from existing audit_log table
- Export uses server-side generation for large datasets

### Blockers
None currently.

This structure gives an agent everything it needs: objective, constraints, current progress, decisions made, and blockers to work around. A new session picks up exactly where the previous one stopped.

Multi-agent scratchpad communication

When running parallel agent sessions, each agent needs its own scratchpad to avoid conflicts. Assign separate files for writing with explicit read permissions:

.claude/scratchpad/
├── agent-1-tests.md      # Agent 1 writes here
├── agent-2-impl.md       # Agent 2 writes here
└── shared-decisions.md   # Both read, neither writes

Configure agents with clear boundaries:

## Agent 1 Instructions
You are writing tests for the new payment system.
Write your progress and findings to `.claude/scratchpad/agent-1-tests.md`.
Read `.claude/scratchpad/agent-2-impl.md` to see implementation progress.
Read `.claude/scratchpad/shared-decisions.md` for architectural decisions.
Do not modify files you don't own.

This separation makes coordination possible without conflicts. Agent 1 checks implementation progress before writing tests that depend on specific method signatures. Agent 2 reads test expectations to understand what the implementation must satisfy. Neither overwrites the other's work.

Communication protocols

Define how agents signal status:

## Implementation Status (Agent 2)

### Current State: IMPLEMENTING
Last updated: 2026-01-15 14:32

### Completed Interfaces
- `PaymentProcessor.process()` - Takes PaymentRequest, returns PaymentResult
- `PaymentValidator.validate()` - Throws ValidationError on failure

### In Progress
- `RefundProcessor.refund()` - 60% complete, return type TBD

### Ready for Tests
- PaymentProcessor (all methods)
- PaymentValidator (all methods)

### Not Ready
- RefundProcessor (interface may change)

Agent 1 reads this and knows to write tests for PaymentProcessor and PaymentValidator but wait on RefundProcessor.

When to use files versus conversation memory

A decision framework:

Use conversation memory when:

Information needed for just the next few turns
Context is small (under 100 tokens)
Task completes within current session
No other agents need the information

Use file-based scratchpads when:

Task spans multiple sessions
Multiple agents need coordination
Progress needs to survive compaction
Information exceeds 200-300 tokens
Work might be interrupted or abandoned
Other developers might continue the task

The filesystem-as-RAM metaphor

Think of the context window as RAM and the filesystem as disk. RAM is fast but volatile and limited. Disk is slower to access but persistent and large.

Working memory for active computation stays in RAM (conversation context). Longer-term storage and anything too large for RAM goes to disk (scratchpad files). Agents that manage this trade-off well, like programs that manage memory well, perform better.

Structured scratchpad formats

For complex tasks, structured formats improve agent comprehension:

The working context format

## Working Context: API Refactoring

### Goal
Migrate REST endpoints from Express to Fastify.

### Current Focus
Converting authentication middleware.

### Key Constraints
- Maintain backward compatibility with v1 clients
- No database schema changes
- Preserve existing test coverage

### Decisions Made
| Decision | Rationale | Date |
|----------|-----------|------|
| Keep session cookies | Client migration planned for Q3 | 2026-01-10 |
| Fastify JWT plugin | Team standard, simpler than custom | 2026-01-12 |

### Files Modified This Session
- src/middleware/auth.ts (in progress)
- src/routes/user.ts (complete)
- src/routes/admin.ts (not started)

### Open Questions
- Should rate limiting move to middleware or stay route-level?
- Error response format: keep Express style or adopt Fastify standard?

This format gives a resuming agent or developer complete context without reading conversation history.

The investigation scratchpad

For debugging or research tasks, capture findings as they emerge:

## Investigation: Memory Leak in Worker Pool

### Symptom
Memory grows 50MB/hour under load. No growth at idle.

### Hypotheses
1. [x] Connection pool not releasing - Ruled out, pool size stable
2. [ ] Event listener accumulation - Testing now
3. [ ] Buffer allocation in message parsing - Not yet tested

### Evidence Collected
- Heap snapshot at 1hr: 847MB
- Heap snapshot at 2hr: 894MB
- Retained objects: 73% MessageHandler instances
- GC running normally, not blocked

### Next Steps
1. Add listener count logging
2. Profile MessageHandler lifecycle
3. Check for missing removeListener calls

### Commands Used
```bash
node --inspect worker.js
# Connected Chrome DevTools, captured heap snapshots


Investigation scratchpads prevent repeating failed hypotheses and preserve the diagnostic journey.

## Cleanup and lifecycle

Scratchpads need active management.
Unlike version-controlled source files, working files accumulate without natural cleanup.

### Cleanup triggers

Remove or archive scratchpad files when:
- Feature ships and PR merges
- Investigation concludes
- Task explicitly abandoned
- Files older than two weeks untouched

### Archive versus delete

For significant investigations or complex features, archive rather than delete:

.claude/scratchpad/ ├── active/ │ └── current-feature.md └── archive/ └── 2026-01/ └── memory-leak-investigation.md


Archived scratchpads become reference for similar future issues without cluttering active working space.

### Git integration

Scratchpad files typically stay untracked:

```text
# Scratchpad files - session-specific working memory
.claude/scratchpad/
SCRATCHPAD.md
scratch*.md

Exception: shared decision files that multiple developers need might warrant tracking:

# Track shared decisions, ignore personal scratchpads
!.claude/scratchpad/shared-decisions.md

Integration with CLAUDE.md

Scratchpads and CLAUDE.md work together but have different jobs. Reference scratchpad patterns in CLAUDE.md so agents know when and how to use them:

## Working Memory

For multi-step tasks, use scratchpad files:
- Create `.claude/scratchpad/<task-name>.md` for task tracking
- Update progress after each completed step
- Clean up scratchpad when task merges

This guidance teaches agents your preferred working memory patterns. Over time, agents follow these patterns without explicit instruction each session.

The next page examines plan mode and multi-turn strategies structuring extended interactions for complex outcomes.

Scratchpad and Task Tracking Patterns

On this page