Planning With Files

---

name: planning-with-files model: reasoning version: 3.0.0 description: > File-based planning for complex tasks. Use persistent markdown files as working memory to survive context resets. Creates task_plan.md, findings.md, and progress.md. Use for any task requiring >5 tool calls, research projects, or multi-step implementations. tags: [planning, context, workflow, manus, memory, complex-tasks]

---

Planning with Files

Use persistent markdown files as your "working memory on disk." Based on context engineering principles from Manus.

Installation

OpenClaw / Moltbot / Clawbot

npx clawhub@latest install planning-with-files

WHAT This Skill Does

Treats the filesystem as persistent memory to overcome context window limitations. Three files track your state:

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

WHEN to Use

Use for:

Multi-step tasks (3+ steps)

Research tasks requiring web search

Building/creating projects from scratch

Tasks spanning >5 tool calls

Anything requiring organization across multiple files

Tasks where losing context would cause rework

Skip for:

Simple questions

Single-file edits

Quick lookups

Tasks completable in 1-2 actions

Keywords: complex task, multi-step, research, build project, create application, plan, organize

The Core Pattern

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

Workflow

Phase 1: Create Planning Files

Before starting ANY complex task, create all three files in your project root:

1. Create task_plan.md — Copy from templates/task_plan.md 2. Create findings.md — Copy from templates/findings.md 3. Create progress.md — Copy from templates/progress.md

Phase 2: Execute with Discipline

Follow these rules during execution:

The 2-Action Rule: > After every 2 view/browser/search operations, IMMEDIATELY save findings to text files.

Visual/multimodal content doesn't persist — write it down before it's lost.

Read Before Decide: Before major decisions, read your plan file. This keeps goals in your attention window after many tool calls.

Update After Act: After completing any phase:

Mark phase status: in_progress → complete

Log any errors encountered

Note files created/modified

Log ALL Errors: Every error goes in the plan file. This prevents repetition.

Phase 3: Handle Errors Systematically

The 3-Strike 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

Critical: if action_failed: next_action != same_action

Phase 4: Verify Completion

Use the 5-Question Reboot Test. If you can answer these, your 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 |

Quick Reference: Read vs Write

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

Session Recovery

When starting a new session, check for previous work:

# Check if planning files exist
ls task_plan.md findings.md progress.md 2>/dev/null
If they exist, read them all before continuing
cat task_plan.md findings.md progress.md

If planning files exist from a previous session: 1. Read all three files to recover context 2. Run git diff --stat to see what changed 3. Update planning files with any missing context 4. Continue from where you left off

Templates

Copy these to start:

templates/task_plan.md — Phase tracking

templates/findings.md — Research storage

templates/progress.md — Session logging

Scripts

Helper scripts for automation:

scripts/init-session.sh — Initialize all planning files

scripts/check-complete.sh — Verify all phases complete

References

references/manus-principles.md — Context engineering principles from Manus

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 |

NEVER Do

1. NEVER start a complex task without task_plan.md — this is non-negotiable 2. NEVER repeat a failed action exactly — track what you tried, mutate the approach 3. NEVER ignore errors — log every error with resolution attempts 4. NEVER rely on memory after >10 tool calls — re-read your plan 5. NEVER skip the 2-Action Rule for visual content — multimodal data gets lost 6. NEVER proceed past 3 failures without escalating — ask the user for help 7. NEVER create planning files in the skill directory — they go in your project root