Planning with Files

Use persistent markdown files as working memory on disk.

Quick Start

• Create planning files -- use /plan or create manually from templates

• Create task_plan.md with goal, phases, and key questions

• Create findings.md for research and decisions

• Create progress.md for session logging

• Re-read the plan before decisions -- refreshes goals in attention

• 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

File Purpose When to Update

task_plan.md

Phases, progress, decisions After each phase completes

findings.md

Research, discoveries, decisions After ANY discovery

progress.md

Session log, test results Throughout the session

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

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

Situation Action Reason

Just wrote a file Don't read it Content still in context

Viewed image/PDF Write findings NOW Multimodal content doesn't persist

Browser returned data Write to file Screenshots don't persist

Starting new phase Read plan/findings Re-orient if context is stale

Error occurred Read relevant file Need current state to fix

Resuming after gap Read all planning files Recover full state

5-Question Reboot Test

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

Question Answer Source

Where am I? Current phase in task_plan.md

Where am I going? Remaining phases

What's the goal? Goal statement in plan

What have I learned? findings.md

What have I done? progress.md

Anti-Patterns

Don't Do Instead

State goals once and forget Re-read plan before decisions

Hide errors and retry silently Log every error to plan file

Stuff everything in context Store large content in files

Start executing immediately Create plan file FIRST

Repeat failed actions Track attempts, mutate approach

Create files in plugin directory Create files in project root

References

• Templates -- starter templates for all three planning files

• Principles -- context engineering principles behind this approach

• Examples -- concrete examples and error recovery patterns