Manage Complex Tasks with Persistent Planning Files

This skill establishes a small set of persistent markdown files (task_plan.md, findings.md, progress.md) as external "working memory on disk" for a coding agent, on the principle that the context window is volatile RAM, while the filesystem is unlimited, persistent disk. Templates ship inside the skill's own directory (${CLAUDE_PLUGIN_ROOT}/templates/), but the three working files themselves are created in the current project directory, not the skill installation folder, so planning state lives alongside the code it describes. task_plan.md tracks phases, progress and decisions and is updated after each phase, marking status from in_progress to complete, logging errors, and noting files touched. findings.md captures research and discoveries as soon as they happen. progress.md is a running session log of what was done and what tests returned.

Several concrete disciplines enforce this. The "2-Action Rule" requires saving key findings to a text file after every two view, browser or search operations, since visual or multimodal information does not otherwise persist in context. A "Read vs Write Decision Matrix" specifies when to read a file back (starting a new phase, after an error, resuming after a gap) and when reading is wasteful (right after writing, when the content is still in context). Every error is logged to the plan file in a table of error, attempt and resolution, and a "Never Repeat Failures" rule forces the next action to differ from a failed one. A "3-Strike Error Protocol" escalates from diagnose-and-fix, to an alternative approach, to a broader rethink of assumptions, and only then to asking the user for guidance.

Use it for multi-step tasks of three or more steps, research tasks, building or creating projects, and any task spanning many tool calls or requiring explicit organization. Skip it for simple questions, single-file edits, or quick lookups, where the overhead of maintaining three tracking files is not worth it.

The skill ships copyable templates for all three files (templates/task_plan.md, templates/findings.md, templates/progress.md) plus two helper scripts: scripts/init-session.sh, which initializes all planning files at once, and scripts/check-complete.sh, which verifies every phase is marked complete. Its output across a session is the three maintained markdown files, which double as a self-check: a "5-Question Reboot Test" (where am I, where am I going, what is the goal, what have I learned, what have I done) should be answerable at any point purely from task_plan.md, findings.md and progress.md if the file discipline was followed.

Agents and developers running long, multi-phase agentic sessions, such as research or multi-file builds, or any work where context can go stale or a session gets interrupted, who need a lightweight, file-based way to recover state (what phase, what was learned, what changed) without relying on the model's own transient memory of the conversation.