Context Manager

Purpose

Maintain working state across phases and handle context limits.

Scratchpad Structure

Global scratchpad (for cross-project work):

~/.claude/scratch/
├── <project-name>/
│   └── <task>/
│       ├── intake.md
│       ├── implement.md
│       ├── verify.md
│       ├── review.md
│       └── notes.md
└── global/
    └── <notes that span projects>

Project-local scratchpad (preferred when in a project):

<project>/docs/scratch/
├── <task>/
│   ├── intake.md
│   ├── implement.md
│   ├── verify.md
│   ├── review.md
│   └── notes.md
└── archive/
    └── <completed task dirs>

Scratchpad Location Rules

1. If inside a git repo with docs/ directory: use docs/scratch/
2. If inside a git repo without docs/: create docs/scratch/
3. If not in a git repo: use ~/.claude/scratch/<context-name>/
4. For work spanning multiple projects: use ~/.claude/scratch/global/

Task Directory Naming

Format: YYYY-MM-DD-<short-descriptor> Example: 2025-01-15-user-auth-flow

When to Write to Scratchpad

• After any decision that would be costly to re-derive
• When switching between tasks or phases
• Before spawning subagents (capture current state)
• When context is getting long (proactive offload)
• Any "improvement ideas" that are out of scope (capture for later)

Scratchpad Format

# <Task> - <Phase> Working State
Project: <project name or path>
Updated: <timestamp>

## Current Status
<one line: what's happening right now>

## Decisions Made
- <decision>: <reasoning> (at <time/commit>)

## Open Questions
- <question> - blocked on <what>

## Next Steps
1. <immediate next action>
2. <after that>

Context Recovery

If context is lost or conversation restarts:

1. Identify project from working directory
2. Read docs/plans/.md for spec
3. Read docs/scratch//* for current state
4. Check git log for recent commits
5. Reconstruct position and continue

Archiving Completed Work

When a task is fully complete:

1. Move task directory to docs/scratch/archive/
2. Design doc remains in docs/plans/ (permanent record)
3. Commit archive with message: chore: archive <task> scratch files

Handoff to Subagents

When spawning a subagent, provide:

• Specific task description (bounded)
• Relevant spec section (not whole spec)
• Files to read (explicit list)
• Success criteria (how to know when done)
• Where to write output (if persisting state)

Do NOT provide:

• Entire conversation history
• Unrelated context
• Vague "figure it out" instructions