planning-with-files

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Planning with Files

基于文件的规划

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

像Manus一样工作：使用持久化的Markdown文件作为你的“磁盘工作记忆”。

FIRST: Check for Previous Session

第一步：检查之前的会话

Before starting work, check for unsynced context from a previous session:

Note: The
scripts/
directory is inside this skill's installation folder.

bash

undefined

开始工作前，检查之前会话中未同步的上下文：

注意：
scripts/
目录位于此skill的安装文件夹内。

bash

undefined

Linux/macOS

python scripts/session-catchup.py "$(pwd)"


```powershell

python scripts/session-catchup.py "$(pwd)"


```powershell

Windows PowerShell

python "scripts\session-catchup.py" (Get-Location)


**If you cannot find the script:**
Ask your agent to locate and run the bundled `session-catchup.py` script from the `planning-with-files` skill.

If catchup report shows unsynced context:
1. Run `git diff --stat` to see actual code changes
2. Read current planning files
3. Update planning files based on catchup + git diff
4. Then proceed with task

python "scripts\session-catchup.py" (Get-Location)


**如果找不到该脚本：**
请让你的agent定位并运行`planning-with-files` skill中附带的`session-catchup.py`脚本。

如果恢复报告显示存在未同步的上下文：
1. 运行`git diff --stat`查看实际的代码变更
2. 阅读当前的规划文件
3. 根据恢复内容和git diff更新规划文件
4. 然后再继续任务

Important: Where Files Go

重要提示：文件存放位置

Templates are in
```
templates/
```
inside this skill
Your planning files go in your project directory

Location	What Goes There
Skill directory	Templates, scripts, reference docs
Your project directory	`task_plan.md` , `findings.md` , `progress.md`

模板文件位于此skill内的
```
templates/
```
目录中
你的规划文件需要存放在你的项目目录中

位置	存放内容
Skill目录	模板、脚本、参考文档
你的项目目录	`task_plan.md` 、 `findings.md` 、 `progress.md`

Quick Start

快速开始

Before ANY complex task:

Create
task_plan.md
— Use templates/task_plan.md as reference
Create
findings.md
— Use templates/findings.md as reference
Create
progress.md
— Use templates/progress.md as reference
Re-read plan before decisions — Refreshes goals in attention window
Update after each phase — Mark complete, log errors

Note: Planning files go in your project root, not the skill installation folder.

在执行任何复杂任务之前：

创建
task_plan.md
— 参考templates/task_plan.md模板
创建
findings.md
— 参考templates/findings.md模板
创建
progress.md
— 参考templates/progress.md模板
做决策前重新阅读规划 — 刷新注意力窗口中的目标
每个阶段后更新文件 — 标记完成状态，记录错误

注意： 规划文件要放在你的项目根目录，而非skill安装文件夹。

The Core Pattern

核心模式

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

→ Anything important gets written to disk.

上下文窗口 = 内存（易失性，容量有限）
文件系统 = 磁盘（持久性，容量无限）

→ 任何重要内容都要写入磁盘。

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

文件	用途	更新时机
`task_plan.md`	阶段划分、进度跟踪、决策记录	每个阶段完成后
`findings.md`	研究内容、发现成果	任何发现产生后
`progress.md`	会话日志、测试结果	会话全程

Critical Rules

关键规则

1. Create Plan First

1. 先创建规划

Never start a complex task without

task_plan.md

. Non-negotiable.

在没有

task_plan.md

的情况下，绝不要开始复杂任务。这是不可协商的要求。

2. The 2-Action Rule

2. 两步操作规则

"After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."

This prevents visual/multimodal information from being lost.

“每完成2次查看/浏览/搜索操作后，立即将关键发现保存到文本文件中。”

这可以防止视觉/多模态信息丢失。

3. Read Before Decide

3. 决策前先阅读

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

在做出重大决策前，阅读规划文件。这能让目标始终保持在你的注意力窗口中。

4. Update After Act

4. 行动后更新

After completing any phase:

Mark phase status:
```
in_progress
```
→
```
complete
```
Log any errors encountered
Note files created/modified

完成任何阶段后：

更新阶段状态：
```
in_progress
```
→
```
complete
```
记录遇到的任何错误
标注创建/修改的文件

5. Log ALL Errors

5. 记录所有错误

Every error goes in the plan file. This builds knowledge and prevents repetition.

markdown

undefined

所有错误都要记录到规划文件中。这能积累知识并避免重复犯错。

markdown

undefined

Errors Encountered

遇到的错误

Error	Attempt	Resolution
FileNotFoundError	1	Created default config
API timeout	2	Added retry logic

undefined

错误	尝试次数	解决方法
FileNotFoundError	1	创建默认配置
API超时	2	添加重试逻辑

undefined

6. Never Repeat Failures

6. 绝不重复失败操作

if action_failed:
    next_action != same_action

Track what you tried. Mutate the approach.

if action_failed:
    next_action != same_action

记录你尝试过的方法，调整操作方式。

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

第一次尝试：诊断并修复
  → 仔细阅读错误信息
  → 确定根本原因
  → 应用针对性修复

第二次尝试：换一种方法
  → 还是同一个错误？尝试不同的方法
  → 换个工具？换个库？
  → 绝不重复完全相同的失败操作

第三次尝试：重新审视整体方案
  → 质疑之前的假设
  → 搜索解决方案
  → 考虑更新规划

三次尝试失败后：向用户求助
  → 说明你尝试过的方法
  → 分享具体的错误信息
  → 请求指导

Read vs Write Decision Matrix

读取与写入决策矩阵

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

场景	操作	原因
刚写完一个文件	不要读取	内容仍在上下文中
查看过图片/PDF	立即写入发现内容	多模态信息需转为文本，避免丢失
浏览器返回数据	写入文件	截图无法持久保存
开始新阶段	阅读规划/发现文件	如果上下文已过期，重新定位方向
发生错误	阅读相关文件	需要当前状态来修复问题
间隔后恢复工作	阅读所有规划文件	恢复状态

The 5-Question Reboot Test

五问题重启测试

If you can answer these, your context management 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

如果你能回答这些问题，说明你的上下文管理是可靠的：

问题	答案来源
我当前处于什么阶段？	`task_plan.md` 中的当前阶段
我接下来要去哪里？	剩余的阶段
目标是什么？	规划中的目标陈述
我学到了什么？	`findings.md`
我已经完成了什么？	`progress.md`

When to Use This Pattern

何时使用此模式

Use for:

Multi-step tasks (3+ steps)
Research tasks
Building/creating projects
Tasks spanning many tool calls
Anything requiring organization

Skip for:

Simple questions
Single-file edits
Quick lookups

适用场景：

多步骤任务（3步及以上）
研究任务
构建/创建项目
需要多次工具调用的任务
任何需要组织管理的工作

不适用场景：

简单问题
单文件编辑
快速查询

Templates

模板

Copy these templates to start:

templates/task_plan.md — Phase tracking
templates/findings.md — Research storage
templates/progress.md — Session logging

复制以下模板开始使用：

templates/task_plan.md — 阶段跟踪
templates/findings.md — 研究内容存储
templates/progress.md — 会话日志记录

Scripts

脚本

Helper scripts for automation:

```
scripts/init-session.sh
```
— Initialize all planning files
```
scripts/check-complete.sh
```
— Verify all phases complete
```
scripts/session-catchup.py
```
— Recover context from previous session (v2.2.0)

用于自动化的辅助脚本：

```
scripts/init-session.sh
```
— 初始化所有规划文件
```
scripts/check-complete.sh
```
— 验证所有阶段是否完成
```
scripts/session-catchup.py
```
— 恢复之前会话的上下文（v2.2.0）

Advanced Topics

高级主题

Manus Principles: See reference.md
Real Examples: See examples.md

Manus原则： 查看reference.md
实际示例： 查看examples.md

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

不要做	应该做什么
使用TodoWrite进行持久化存储	创建 `task_plan.md` 文件
只声明一次目标就遗忘	决策前重新阅读规划
隐藏错误并默默重试	将错误记录到规划文件中
把所有内容塞进上下文	将大量内容存储到文件中
立即开始执行	先创建规划文件
重复失败的操作	记录尝试次数，调整方法
在skill目录中创建文件	在你的项目目录中创建文件