home / skills / codingheader / myskills / planning-with-files

planning-with-files skill

safe

This skill helps you manage complex multi-step tasks by creating and updating task_plan.md, findings.md, and progress.md to persist project state.

npx playbooks add skill codingheader/myskills --skill planning-with-files

Review the files below or copy the command above to add this skill to your agents.

Files (6)

SKILL.md

3.4 KB

---
name: planning-with-files
description: Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-step tasks, research projects, or any task requiring >5 tool calls.
license: MIT
---

# Planning with Files

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

## Core Principle

```
Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.
```

## Quick Start

Before ANY complex task, create these three files:

1. **task_plan.md** — Track phases and progress
2. **findings.md** — Store research and discoveries
3. **progress.md** — Session log and test results

See references/ for starting templates.

## 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
Never start a complex task without `task_plan.md`. Non-negotiable.

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

This prevents visual/multimodal information from being lost.

### 3. Read Before Decide
Before major decisions, read the plan file. This keeps goals in your attention window.

### 4. Update After Act
After completing any phase:
- Mark phase status: `in_progress` → `complete`
- Log any errors encountered
- Note files created/modified

### 5. Log ALL Errors
Every error goes in the plan file. This builds knowledge and prevents repetition.

### 6. Never Repeat Failures
```
if action_failed:
    next_action != same_action
```
Track what you tried. Mutate the approach.

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

## When to Use This Pattern

**Use for:**
- Multi-step tasks (3+ steps)
- Research tasks
- Building/creating projects
- Tasks spanning many tool calls

**Skip for:**
- Simple questions
- Single-file edits
- Quick lookups

## Templates

- references/task_plan.md — Phase tracking template
- references/findings.md — Research storage template
- references/progress.md — Session logging template

## Advanced Topics

- **Manus Principles:** See references.md for complete context engineering patterns
- **Real Examples:** See examples.md for practical implementations

## Anti-Patterns

| Don't | Do Instead |
|-------|------------|
| 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 |

---

**This pattern is why Manus went from launch to $2B acquisition in 8 months.**

Overview

This skill implements a Manus-style file-based planning workflow to manage complex, multi-step tasks. It automatically creates and maintains task_plan.md, findings.md, and progress.md so important context is persisted to disk. Use it to structure long-running work, coordinate research, and avoid lost context across many tool calls.

How this skill works

On start, the skill creates three markdown files and seeds them with templates. During execution it writes decisions, discoveries, and session logs to the appropriate files whenever key events occur. It enforces rules like creating the plan first, saving findings after every two information-gathering actions, and logging all errors to drive iterative fixes.

When to use it

Starting a multi-step project with 3+ phases or many tool calls
Conducting research that produces discoverable artifacts and notes
Building or integrating systems where progress must be auditable
Tasks expected to span multiple sessions or collaborators
Any workflow where losing intermediate context would be costly

Best practices

Always create task_plan.md before taking major actions
Save discoveries to findings.md after every two view/search operations
Read task_plan.md before making major decisions or changing direction
Log every error, attempt, and result to progress.md and task_plan.md
Follow the 3-strike protocol: diagnose, try alternatives, then rethink

Example use cases

Researching and drafting a technical whitepaper across multiple sessions
Coordinating a multi-step engineering task with build/test cycles and error handling
Running a long investigative workflow that requires collecting sources and notes
Developing a feature that requires iterative trials, logs, and decision checkpoints
Managing a cross-team project where persistent artifacts support handoffs

FAQ

What files does this skill create and why?

It creates task_plan.md for phases and decisions, findings.md for research and discoveries, and progress.md for session logs and test results to keep critical context persistent and searchable.

How often should I write to the files?

Write to findings.md after any discovery and at least once after every two view/browser/search actions. Update task_plan.md after each phase and log session activity continuously in progress.md.