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:

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:

Quick Reference: Read vs Write

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

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