planning-with-files_skill

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