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