name	planning-with-files
description	Use when user explicitly requests planning with files, or asks for persistent tracking of a complex task.

Planning with Files

Use persistent markdown files as external memory for complex tasks. Files survive context limits and session boundaries.

Use TodoWrite to decompose phases into executable tasks. Before closing session, use Question to confirm findings, decisions, and deliverables are satisfactory.

When to Use

User explicitly requests planning/tracking with files
Complex multi-session tasks
Research-heavy work requiring persistent notes
Tasks where decisions and rationale need to be preserved

When NOT to Use

Simple single-session tasks (use Plan agent instead)
Quick fixes or small changes
Tasks with clear requirements needing no research

Directory Convention

All planning files go in _plans/ with date-prefixed task folders:

_plans/
  2026-01-08-dark-mode-toggle/
    plan.md
    research.md
    decisions.md
  2026-01-09-api-auth-refactor/
    plan.md
    scratch.md

Naming: YYYY-MM-DD-task-name (kebab-case, concise description)

File Types

Create files based on what the task needs, not a fixed pattern:

Type	When to Create	Content
`plan.md`	Always	Goal, phases, status, errors encountered
`research.md`	Research-heavy tasks	Sources, findings, synthesized data
`decisions.md`	Tradeoff decisions	ADRs, options considered, rationale
`scratch.md`	Complex reasoning	Drafts, working notes, exploratory code
`[deliverable].md`	Final outputs	Reports, summaries, documentation

plan.md Template

# Plan: [Brief Description]

## Goal
[One sentence describing the end state]

## Phases
- [ ] Phase 1: [Description]
- [ ] Phase 2: [Description]
- [ ] Phase 3: [Description]

## Status
**Current:** [What's happening now]

## Decisions
- [Decision]: [Rationale]

## Errors Encountered
- [Error]: [Resolution]

research.md Template

# Research: [Topic]

## Sources
- [Source]: [Key findings]

## Findings
### [Category]
- [Finding]

decisions.md Template

# Decisions: [Task]

## [Decision Title]
**Status:** Decided | Pending
**Options:**
1. [Option A] - [Pros/Cons]
2. [Option B] - [Pros/Cons]

**Choice:** [Selected option]
**Rationale:** [Why]

Task System Integration

Planning files are for investigation; TodoWrite tasks are for execution.

Workflow:

Create _plans/ directory and plan.md
Research and document findings
Make decisions, document rationale
Decompose phases into executable TodoWrite tasks

Recommended Tools

Tool	When to Use
Explore subagent	Search codebase, find patterns, understand existing structure before planning
Question	Clarify requirements, validate assumptions, confirm decisions before proceeding

Use these proactively during investigation to avoid wrong assumptions and wasted effort.

Success Criteria

Planning is complete when:

plan.md exists with clear goal and phases
All phases marked complete or explicitly deferred
Key decisions documented with rationale
Errors encountered are logged with resolutions
User confirms deliverables via Question

Critical Rules

Refresh Goals When Context Gets Long

After many tool calls (~20+), re-read plan.md before major decisions. This brings goals back into the attention window.

1. Store, Don't Stuff

Large outputs go to files, not context. Keep paths in working memory, content in files.

2. Log All Errors

Every error goes in plan.md under "Errors Encountered". This builds knowledge and shows recovery.

3. Decisions Need Rationale

Don't just record what you decided - record WHY. Future-you needs this context.

4. Update Status Immediately

Mark phases complete as soon as they're done. Don't batch status updates.

Anti-Patterns

Don't	Do Instead
Create files in project root	Use `_plans/YYYY-MM-DD-name/`
State goals once and forget	Re-read plan.md when context is long
Hide errors and retry silently	Log errors with resolution
Stuff everything in context	Store large content in files
Start executing immediately	Create plan.md first for complex tasks

planning-with-files