pi-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 Pi to locate it for you:
`Run the 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)


**如果找不到该脚本：**
请让Pi帮你定位它：
`Run the session-catchup.py script from the planning-with-files skill`

如果会话恢复报告显示存在未同步上下文：
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.

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安装目录创建文件	在你的项目目录创建文件