planning-with-files

Planning with Files - Claude Complex Task File Planning Skill

Skill Overview

Planning with Files is a Claude skill that implements Manus-style file-based planning. By creating three persistent files—task_plan.md, findings.md, and progress.md—it helps users effectively manage complex multi-step tasks, research projects, and development work that requires lots of tool calls.

Use Cases

1. Complex Multi-Step Tasks

When your task needs to run more than 5 tool calls, or includes 3+ interrelated steps, this skill helps you build a clear task structure, track the completion status of each phase, and ensure nothing important is missed.

2. Research Projects and Exploration

During codebase research, technical investigation, or issue diagnosis, the findings.md file can serve as your research notes—recording all important discoveries and insights—so that multi-modal information (e.g., browser content, image analysis) isn’t forgotten in the context window.

3. Long-Term Development Projects

For development work spanning multiple sessions, the three planning files provide persistent “disk-based working memory,” allowing you to resume progress at any time, revisit completed phases, and review recorded errors and their solutions.

Core Features

1. Three-File Planning System

task_plan.md: Records task phases, current progress, and key decisions; update the status after each phase is completed

findings.md: Stores discoveries, insights, and important information from the research process; follow the “2-Action rule” to save promptly

progress.md: Session logs and test result records to help track work history

2. Smart Error Handling Mechanism

Built-in “3-Strike error protocol” guides you to handle failures systematically: first, diagnose and fix; second, try an alternative approach; third, rethink the direction. After three failed attempts, escalate to the user. All errors are recorded in the planning files to avoid repeating the same failures.

3. Context Management Best Practices

Provides methods such as “read the plan before making decisions” and “5-question restart testing” to ensure goals remain clear throughout long, complex tasks. The file system acts as a persistent external memory module that compensates for the limited capacity of the context window.

Frequently Asked Questions

What types of tasks is planning-with-files suitable for?

This skill is designed specifically for complex tasks requiring more than 5 tool calls. Typical scenarios include: multi-step code refactoring, large-scale research projects, debugging work across multiple files, and technical investigations that require repeated searching and browsing. For simple single-file edits or quick queries, using the corresponding tools directly is more efficient.

What are the differences and purposes of the three planning files?

task_plan.md is your task blueprint, recording phase breakdowns, progress status, and key decisions. findings.md is your research notes, recording any valuable information you discover along the way. progress.md is your session log, recording operations and test results in chronological order. Together, they ensure important information isn’t lost when switching context.

Why use files instead of the built-in TodoWrite to manage tasks?

Files are persistent—they remain after the session ends, making them suitable for projects that span days or weeks. TodoWrite only applies within the current session. More importantly, files can be version-controlled (Git), shared with other developers, and aren’t limited by the context window size—so they can hold large amounts of task details and research findings.