Task Externalization

Task Externalization System

Maintain continuity for large tasks across context compactions and session resets by externalizing task state to .scratch/tasks/.

When to Use

Use task externalization when:

• Starting large/complex tasks (5+ files, architectural changes)
• After /compact or /new commands
• Context window is getting full during multi-file work
• Task spans multiple sessions

Two-File Structure

1. Overview File: .scratch/tasks.md

Tracks overall state across all tasks:

• Global Context: Shared decisions/constraints
• Current Task: Which task file is active
• Task List: All tasks with status (pending, in progress, completed)
• Cross-task Notes: Dependencies, blockers

2. Task Files: .scratch/tasks/{name}.md

Each task file contains:

• Goal: What needs to be accomplished
• Context: Background, decisions, constraints
• Files to Modify: List of files to change
• Implementation Plan: Step-by-step approach
• Progress Notes: What's done, what remains, blockers
• Testing: How to verify

See references/file-structure.md for complete examples

Quick Workflow

Starting session or after /compact//new:

1. Check if .scratch/tasks.md exists
2. If yes: Read it + current task file
3. Summarize and continue

Starting new large task:

1. Create .scratch/tasks/ directory
2. Create/update overview file
3. Create task file with plan
4. Update overview to mark as current
5. Begin implementation

During work:

• Update Progress Notes as steps complete
• Note blockers and decisions

Completing task:

1. Mark complete in task file
2. Update overview: [x]
3. Update current task to next pending

See references/workflows.md for detailed workflows

Important Notes

• Keep progress notes current for accurate recovery
• Don't delete task files until entire effort is complete
• .scratch/ is already in gitignore
• Task files are read/updated throughout work