planning-with-files

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:

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:

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

Recommended Tools

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

See Also

• reference.md - Manus context engineering principles
• examples.md - Real task examples with different file combinations