> ## Documentation Index
> Fetch the complete documentation index at: https://docs.newenergycoder.club/llms.txt
> Use this file to discover all available pages before exploring further.

# planning-with-files

> Implements Manus-style file-based planning for complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when starting complex multi-ste…

| 项目 | 内容                                                                                                                                                                                                                                                                         |
| -- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 来源 | [skills/planning-with-files/SKILL.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/SKILL.md)                                                                                                                       |
| 分类 | 开发工程 & 工作流                                                                                                                                                                                                                                                                 |
| 安装 | 克隆 [Skill 分支](https://github.com/new-energy-coder-club/new_energy_coder_club/tree/Skill) 后，将 `skills/planning-with-files/` 目录复制到 `~/.claude/skills/`（Claude Code）、`~/.trae/skills/`（Trae IDE）或 `~/.qclaw/skills/`（QClaw/OpenClaw），详见 [Skill 安装方式](/community/skill-branch) |

# Planning with Files

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

## FIRST: Check for Previous Session (v2.2.0)

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

```bash theme={null}
# Linux/macOS
$(command -v python3 || command -v python) ${CLAUDE_PLUGIN_ROOT}/scripts/session-catchup.py "$(pwd)"
```

```powershell theme={null}
# Windows PowerShell
& (Get-Command python -ErrorAction SilentlyContinue).Source "$env:USERPROFILE\.claude\skills\planning-with-files\scripts\session-catchup.py" (Get-Location)
```

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

## Important: Where Files Go

* **Templates** are in `${CLAUDE_PLUGIN_ROOT}/templates/`
* **Your planning files** go in **your project directory**

| Location                                   | What Goes There                              |
| ------------------------------------------ | -------------------------------------------- |
| Skill directory (`${CLAUDE_PLUGIN_ROOT}/`) | Templates, scripts, reference docs           |
| Your project directory                     | `task_plan.md`, `findings.md`, `progress.md` |

## Quick Start

Before ANY complex task:

1. **Create `task_plan.md`** — Use [templates/task\_plan.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/templates/task_plan.md) as reference
2. **Create `findings.md`** — Use [templates/findings.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/templates/findings.md) as reference
3. **Create `progress.md`** — Use [templates/progress.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/templates/progress.md) as reference
4. **Re-read plan before decisions** — Refreshes goals in attention window
5. **Update after each phase** — Mark complete, log errors

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

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

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

```markdown theme={null}
## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |
```

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

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

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

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

## Templates

Copy these templates to start:

* [templates/task\_plan.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/templates/task_plan.md) — Phase tracking
* [templates/findings.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/templates/findings.md) — Research storage
* [templates/progress.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/templates/progress.md) — Session logging

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

## Advanced Topics

* **Manus Principles:** See [reference.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/reference.md)
* **Real Examples:** See [examples.md](https://github.com/new-energy-coder-club/new_energy_coder_club/blob/Skill/skills/planning-with-files/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    |