planning-with-files

Planning with Files

Work like Manus: Use persistent markdown files as your "working memory on disk."

Important: Where Files Go

When using this skill:

| Location | What Goes There | |----------|-----------------| | Skill directory (${CLAUDE_PLUGIN_ROOT}/) | Templates, scripts, reference docs | | Your project directory | task_plan.md, findings.md, progress.md |

This ensures your planning files live alongside your code, not buried in the skill installation folder.

Quick Start

Before ANY complex task:

1. Create task_plan.md in your project — Use templates/task_plan.md as reference 2. Create findings.md in your project — Use templates/findings.md as reference 3. Create progress.md in your project — Use templates/progress.md as reference 4. Re-read plan before decisions — Refreshes goals in attention window 5. Update after each phase — Mark complete, log errors

> Note: All three planning files should be created in your current working directory (your project root), not in the skill's installation folder.

The Core Pattern

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)
→ Anything important gets written to disk.

File Purposes

| File | Purpose | When to Update | |------|---------|----------------| | task_plan.md | Phases, progress, decisions | After each phase | | findings.md | Research, discoveries | After ANY discovery | | progress.md | Session log, test results | Throughout session |

Critical Rules

1. Create Plan First

2. The 2-Action Rule

This prevents visual/multimodal information from being lost.

3. Read Before Decide

4. Update After Act

5. Log ALL Errors

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

6. Never Repeat Failures

if action_failed:
    next_action != same_action

The 3-Strike Error Protocol

ATTEMPT 1: Diagnose & Fix
  → Read error carefully
  → Identify root cause
  → Apply targeted fix
ATTEMPT 2: Alternative Approach
  → Same error? Try different method
  → Different tool? Different library?
  → NEVER repeat 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
  → Share the specific error
  → Ask for guidance

Read vs Write Decision Matrix

| Situation | Action | Reason | |-----------|--------|--------| | Just wrote a file | DON'T read | Content still in context | | Viewed image/PDF | Write findings NOW | Multimodal → text before lost | | Browser returned data | Write to file | Screenshots don't persist | | Starting new phase | Read plan/findings | Re-orient if context stale | | Error occurred | Read relevant file | Need current state to fix | | Resuming after gap | Read all planning files | Recover state |

The 5-Question Reboot Test

If you can answer these, your context management 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 |

When to Use This Pattern

Use for:

Skip for:

Templates

Copy these templates to start:

Scripts

Helper scripts for automation:

Advanced Topics

Anti-Patterns

| Don't | Do Instead | |-------|------------| | Use TodoWrite for persistence | Create task_plan.md file | | State goals once and forget | Re-read plan before decisions | | Hide errors and retry silently | Log errors 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 skill directory | Create files in your project |

Before ANY complex task:

1. Create task_plan.md in your project — Use templates/task_plan.md as reference 2. Create findings.md in your project — Use templates/findings.md as reference 3. Create progress.md in your project — Use templates/progress.md as reference 4. Re-read plan before decisions — Refreshes goals in attention window 5. Update after each phase — Mark complete, log errors

> Note: All three planning files should be created in your current working directory (your project root), not in the skill's installation folder.