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](references/templates.md)
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.

```markdown
## 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](references/templates.md) -- starter templates for all
  three planning files
- [Principles](references/principles.md) -- context engineering
  principles behind this approach
- [Examples](references/examples.md) -- concrete examples and error
  recovery patterns