- name
- planning-with-files
- model
- reasoning
- version
- 3.0.0
- description
- >
- 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-filesWHAT 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:
- Create
task_plan.md— Copy from templates/task_plan.md - Create
findings.md— Copy from templates/findings.md - 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 guidanceCritical: 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.mdIf planning files exist from a previous session:
- Read all three files to recover context
- Run
git diff --statto see what changed - Update planning files with any missing context
- 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 filesscripts/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
- NEVER start a complex task without task_plan.md — this is non-negotiable
- NEVER repeat a failed action exactly — track what you tried, mutate the approach
- NEVER ignore errors — log every error with resolution attempts
- NEVER rely on memory after >10 tool calls — re-read your plan
- NEVER skip the 2-Action Rule for visual content — multimodal data gets lost
- NEVER proceed past 3 failures without escalating — ask the user for help
- NEVER create planning files in the skill directory — they go in your project root