seikaikyo/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

| 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
| 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

| 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