playbooks

home / skills / itou-daiki / easy_stat_edu / planning-with-files

planning-with-files skill

/.agent/skills/planning-with-files

This skill enforces externalized memory by writing critical findings and plans to disk, ensuring long-term coherence during complex tasks.

npx playbooks add skill itou-daiki/easy_stat_edu --skill planning-with-files

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

Files (3)
SKILL.md
3.9 KB
---
name: Planning with Files
description: A comprehensive context management system for AI agents. Enforces externalizing memory to disk to prevent hallucinations and maintain long-term coherence.
---

# Planning with Files (v2.2.0)

> **The Core Pattern**:  
> `Context Window = RAM` (Volatile, Limited)  
> `Filesystem = Disk` (Persistent, Unlimited)  
> **Rule**: Anything important MUST be written to disk immediately.

## 1. Critical Rules (Non-Negotiable)

### 1.1 Create Plan First
Never start a complex task (coding, research, refactoring) without creating or updating `task_plan.md`. This is your anchor.

### 1.2 The 2-Action Rule
"After every **2** view/browser/search operations, **IMMEDIATELY** save key findings to `findings.md`."
- Prevents "context window washouts" where new tokens push out old insights.
- If you read a file and find a bug, log it in `findings.md` *before* trying to fix it.

### 1.3 Read Before Decide
Before making a major decision (architecture change, deletion, new library), **read the plan file**.
- This refreshes your "Attention Window" with the original goals and constraints.

### 1.4 Update After Act
After completing a phase or a significant step:
1.  Mark the item as `[x]` in `task_plan.md` or `progress.md`.
2.  Log any errors encountered in `task_plan.md` (Errors Section).
3.  Note new files created.

### 1.5 The 3-Strike Error Protocol
If an action fails (e.g., test failure, API error, file not found):
1.  **Attempt 1: Diagnose & Fix**: Read error, identify root cause, apply fix.
2.  **Attempt 2: Alternative Approach**: If the exact same error happens, **STOP**. Do not try the same thing again. Use a different tool, library, or method.
3.  **Attempt 3: Broader Rethink**: Question your assumptions. Is the file path wrong? Is the logic flawed?
4.  **AFTER 3 FAILURES**: **Escalate to User**. Stop spinning your wheels.

## 2. File Goals

### `task_plan.md` (The Strategy)
- **Purpose**: Defines *what* we are doing and *how*.
- **Contains**: Objectives, Step-by-step implementation plan, Current Status, Error Log.
- **Update Frequency**: At the start of a task, and after every major phase completion.

### `findings.md` (The Memory)
- **Purpose**: Stores raw information, code snippets, documentation, and "aha!" moments.
- **Contains**: Relevant file content summaries, API references, decisions made, bug causes.
- **Update Frequency**: **High**. Every 2-3 tool calls during research/debugging.

### `progress.md` (The Journal)
- **Purpose**: A chronological log of actions taken (optional if using `task.md` heavily/Agentic Mode).
- **Contains**: Timestamps, specific commands run, test results.

## 3. Workflow Implementation

### Phase 1: Initialization / Planning
1.  **Check Context**: Run `ls -R` or `list_dir` to see if planning files exist.
2.  **Create/Read**:
    - **Task Plan**: Create `task_plan.md` using `templates/task_plan.md` as a guide.
    - **Findings**: Create `findings.md` using `templates/findings.md` for research notes.
    - *Note*: You can use `read_file .agent/skills/planning-with-files/templates/task_plan.md` to see the structure.

### Phase 2: Execution (The Loop)
1.  **Read** code/docs.
2.  **Write** findings to `findings.md` (2-Action Rule).
3.  **Update** `task_plan.md` if the plan changes based on findings.
4.  **Act** (Write code, run command).
5.  **Verify** result.
6.  **Log** outcome to `progress.md` or `task_plan.md`.

## 4. When to Use
- **USE FOR**: Multi-step tasks, Debugging complex bugs, Feature implementation, Refactoring.
- **SKIP FOR**: Trivial one-shot questions (e.g., "What time is it?", "Fix this typo on line 10").

## 5. Anti-Patterns (What NOT to do)
- **Storing everything in RAM**: Relying on your context window to remember what you read 10 turns ago.
- **"I'll remember that"**: You won't. Write it down.
- **Looping on Errors**: Retrying the same failing command 5 times hoping it works. (Use 3-Strike Protocol).

Overview

This skill enforces a disk-first context management pattern for AI agents to prevent hallucinations and preserve long-term coherence. It requires creating and maintaining a small set of plain-text planning files (task_plan.md, findings.md, progress.md) so important state is never only in volatile memory. The approach is lightweight, deterministic, and suited to multi-step engineering or research workflows.

How this skill works

The skill makes the filesystem the authoritative memory store: anything important must be written to disk immediately. It prescribes a planning-first loop: create or read task_plan.md, capture discoveries to findings.md after every two external reads/actions, execute steps, then record outcomes and errors to task_plan.md or progress.md. A 3-strike error protocol forces diagnosis, alternative approaches, and escalation to the user after repeated failures.

When to use it

  • Multi-step engineering tasks like feature development, refactors, or migrations
  • Complex debugging where findings and hypotheses must be preserved
  • Long-running research or design investigations that exceed the agent's context window
  • Agentic workflows that coordinate multiple tools, files, or subprocesses
  • Avoid for single-shot trivial tasks or simple lookups

Best practices

  • Always create or read task_plan.md before making architecture or deletion decisions
  • After every two reads/browse/search actions, append key notes to findings.md
  • Mark completed items and log errors in task_plan.md immediately after actions
  • Follow the 3-strike protocol: diagnose, try alternative, then rethink before escalating
  • Keep findings concise: summaries, code snippets, causes, and decisive conclusions

Example use cases

  • Implementing a new feature across multiple files while tracking design decisions in task_plan.md
  • Debugging an intermittent test failure and recording reproduction steps and fixes in findings.md
  • Refactoring a module: plan steps, note code smells and partial results, and log progress
  • Researching API behavior: store relevant snippets and links in findings.md to avoid re-fetching
  • Coordinating chained tool actions (build, test, deploy) with progress.md timestamps and outcomes

FAQ

What if I forget to write to disk after two actions?

Treat it as a learning event: pause, summarize recent findings into findings.md immediately, and continue. The rule exists to avoid context loss.

When should I update task_plan.md versus progress.md?

Use task_plan.md for strategy, objectives, and error logs. Use progress.md as an optional chronological journal of commands, timestamps, and test outputs when you need detailed step-by-step history.