Planning With Files

Planning with Files

Use persistent markdown files as working memory on disk.

Quick Start

1. Create planning files -- use /plan or create manually from templates 2. Create `task_plan.md` with goal, phases, and key questions 3. Create `findings.md` for research and decisions 4. Create `progress.md` for session logging 5. Re-read the plan before decisions -- refreshes goals in attention 6. Update after each phase -- mark status, log errors

When to Use

• Multi-step tasks (3+ phases)
• Research projects requiring many searches
• Building or creating projects with multiple files
• Tasks spanning many tool calls (>10)
• Any work where losing track of goals would be costly
• Tasks that may span multiple sessions

When NOT to Use

• Simple questions or quick lookups
• Single-file edits with obvious scope
• Tasks completable in under 5 tool calls
• Conversational exchanges without implementation

Core Pattern

Context Window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)

Anything important gets written to disk.

After many tool calls, the original goal drifts out of the attention window. Reading task_plan.md brings it back. This is the single most important pattern in file-based planning.

File Purposes

All three files go in the project root, not the plugin directory.

Critical Rules

1. Create Plan First

Never start a complex task without task_plan.md. This is non-negotiable. The plan is your persistent memory.

2. The 2-Action Rule

After every 2 search, browse, or read operations, immediately save key findings to findings.md. Multimodal content (images, browser results, PDF contents) does not persist in context -- capture it as text before it is lost.

3. Read Before Decide

Before any major decision, re-read task_plan.md. This pushes goals and context back into the recent attention window, counteracting the "lost in the middle" effect that occurs after ~50 tool calls.

[Original goal -- far away in context, forgotten]
...many tool calls...
[Recently read task_plan.md -- gets ATTENTION]
→ Now make the decision with goals fresh in context

4. Update After Act

After completing any phase:

• Mark phase status: in_progress -> complete
• Log any errors encountered in the Errors table
• Note files created or modified in progress.md

5. Log ALL Errors

Every error goes in task_plan.md. Include the attempt number and resolution. This builds knowledge and prevents repeating failures.

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

6. Never Repeat Failures

If an action failed, the next action must be different. Track what you tried and mutate the approach.

if action_failed:
    next_action != same_action

3-Strike Error Protocol

ATTEMPT 1: Diagnose & Fix
  -> Read error carefully
  -> Identify root cause
  -> Apply targeted fix

ATTEMPT 2: Alternative Approach
  -> Same error? Try a different method
  -> Different tool? Different library?
  -> NEVER repeat the exact same failing action

ATTEMPT 3: Broader Rethink
  -> Question assumptions
  -> Search for solutions
  -> Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  -> Explain what you tried (with attempt log)
  -> Share the specific error
  -> Ask for guidance

Read vs Write Decision Matrix

5-Question Reboot Test

If you can answer these from your planning files, context is solid:

Anti-Patterns

References

• Templates -- starter templates for all

three planning files

• Principles -- context engineering

principles behind this approach

• Examples -- concrete examples and error

recovery patterns

Examples

Bug Fix Task

User request: "Fix the login bug in the authentication module"

task_plan.md after Phase 3

# Task Plan: Fix Login Bug

## Goal
Identify and fix the bug preventing successful login.

## Phases

### Phase 1: Understand the bug report
- [x] Review bug report details
- **Status:** complete

### Phase 2: Locate relevant code
- [x] Search for auth handler
- **Status:** complete

### Phase 3: Identify root cause
- [ ] Trace the TypeError
- **Status:** in_progress

### Phase 4: Implement fix
- [ ] Fix the async/await issue
- **Status:** pending

### Phase 5: Test and verify
- [ ] Run auth test suite
- **Status:** pending

## Key Questions
1. What error message appears?
2. Which file handles authentication?
3. What changed recently?

## Decisions Made
| Decision | Rationale |
|----------|-----------|
| Auth handler is in src/auth/login.ts | Grep found validateToken() here |
| Root cause: user object not awaited | TypeError trace pointed to line 42 |

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| TypeError: Cannot read property 'token' of undefined | 1 | Found: user object not awaited properly |

Key points:

• Phases are broken into discoverable steps
• Decisions record WHERE and WHY, not just WHAT
• The error table captures the actual trace, not a vague description

Error Recovery Pattern

When something fails, don't hide it. Log it and change approach.

Wrong approach

Action: Read config.json
Error: File not found
Action: Read config.json     <- silent retry, same action
Action: Read config.json     <- another retry, still same action

Three identical attempts, no learning, no progress.

Correct approach

Action: Read config.json
Error: File not found

Update task_plan.md:
  ## Errors Encountered
  | Error | Attempt | Resolution |
  |-------|---------|------------|
  | config.json not found | 1 | Will create default config |

Action: Write config.json (create with defaults)
Action: Read config.json
Success!

The error is logged, the approach mutates, and progress is made. This is Rule 6 (Never Repeat Failures) in action.

The Read-Before-Decide Pattern

This is the most important pattern in file-based planning.

[Many tool calls have happened...]
[Context is long, original goal is fading...]

-> Read task_plan.md           <- brings goals back into attention
-> Now make the decision       <- goals are fresh in context

When to apply:

• Before choosing between implementation approaches
• Before starting a new phase
• After a long sequence of search/read operations
• Whenever you feel uncertain about the current direction

The plan file is not just a record -- it is an active tool for maintaining focus across long task sequences.

Context Engineering Principles

The principles behind file-based planning, distilled from Manus's context engineering approach.

Filesystem as External Memory

Context Window = RAM (volatile, limited)
Filesystem     = Disk (persistent, unlimited)

Anything important gets written to disk. The context window is temporary -- it resets, it fills up, it loses older content. Files persist across sessions, have no size limit, and can be selectively re-read when needed.

When compressing context (summarizing, dropping details), always preserve pointers to the full data: keep URLs even if web content is dropped, keep file paths when dropping document contents. Never lose the ability to recover the original.

Manipulate Attention Through Recitation

This is the key insight behind the entire approach.

After ~50 tool calls, models forget original goals. This is the "lost in the middle" effect -- content at the start and end of the context window gets attention, but the middle fades.

The fix: re-read task_plan.md before each major decision. This pushes the goal and current state into the most recent part of the context, where it gets maximum attention.

Start of context: [Original goal -- far away, low attention]
...many tool calls in the middle...
End of context: [Recently read task_plan.md -- HIGH attention]

This is why Manus can handle ~50 tool calls without losing track. The plan file acts as a goal-refresh mechanism.

Keep the Wrong Turns In

Leave failed attempts and error traces in the planning files.

Why:

• Failed actions with stack traces let the model implicitly update

its beliefs about what works

• Reduces repetition of the same mistakes
• Error recovery is one of the clearest signals of effective

agentic behavior

The error table in task_plan.md serves this purpose. Log every failure with the attempt number and what you tried. The next attempt should always be different.

Avoid Repetitive Patterns

Repetitive action-observation pairs cause drift and hallucination. When you notice yourself doing the same thing repeatedly:

• Vary your approach (different tool, different angle)
• Re-read the plan to check if you're still on track
• If stuck after 3 attempts, escalate to the user

Context Offloading

Store full results on disk, keep only references in context.

Practical application:

• Write large search results or API responses to files
• Keep file paths and summaries in context
• Use glob and grep to find information later
• Load details only when needed (progressive disclosure)

This keeps the context window focused on the current task while making all accumulated knowledge accessible through the filesystem.

Source

Based on context engineering principles from Manus.

Planning File Templates

Starter templates for the three planning files. Copy to your project root and fill in the bracketed sections.

task_plan.md

# Task Plan: [Brief Description]

## Goal
[One sentence describing the end state]

## Current Phase
Phase 1

## Phases

### Phase 1: Requirements & Discovery
- [ ] Understand user intent
- [ ] Identify constraints and requirements
- [ ] Document findings in findings.md
- **Status:** in_progress

### Phase 2: Planning & Structure
- [ ] Define technical approach
- [ ] Create project structure if needed
- [ ] Document decisions with rationale
- **Status:** pending

### Phase 3: Implementation
- [ ] Execute the plan step by step
- [ ] Write code to files before executing
- [ ] Test incrementally
- **Status:** pending

### Phase 4: Testing & Verification
- [ ] Verify all requirements met
- [ ] Document test results in progress.md
- [ ] Fix any issues found
- **Status:** pending

### Phase 5: Delivery
- [ ] Review all output files
- [ ] Ensure deliverables are complete
- [ ] Deliver to user
- **Status:** pending

## Key Questions
1. [Question to answer]
2. [Question to answer]

## Decisions Made
| Decision | Rationale |
|----------|-----------|
|          |           |

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
|       |         |            |

findings.md

# Findings & Decisions

## Requirements
-

## Research Findings
-

## Technical Decisions
| Decision | Rationale |
|----------|-----------|
|          |           |

## Resources
-

progress.md

# Progress Log

## Session: [DATE]

### Phase 1: [Title]
- **Status:** in_progress
- **Started:** [timestamp]
- Actions taken:
  -
- Files created/modified:
  -

### Phase 2: [Title]
- **Status:** pending
- Actions taken:
  -
- Files created/modified:
  -

## Test Results
| Test | Input | Expected | Actual | Status |
|------|-------|----------|--------|--------|
|      |       |          |        |        |