Manage Complex Tasks with Persistent Planning Files

Provides a working-memory-on-disk pattern for complex agent tasks - persisting task plans, research findings, and progress logs as project-directory markdown files rather than relying solely on the volatile context window.

Use this skill for multi-step tasks (3+ steps), research tasks, building or creating projects, tasks spanning many tool calls, or anything requiring organization across a long session. Skip it for simple questions, single-file edits, or quick lookups where the overhead of maintaining planning files isn't justified.

Core pattern: the context window acts as volatile, limited RAM while the filesystem acts as persistent, unlimited disk - anything important gets written to disk. Three planning files are created in the project directory (never inside the skill's own installation folder): task_plan.md (phases, progress, decisions, updated after each phase), findings.md (research and discoveries, updated after any discovery), and progress.md (session log and test results, updated throughout the session), each with a corresponding template in the skill directory.

Six critical rules govern usage: always create the plan first before starting any complex task (non-negotiable); follow the 2-action rule, saving key findings to text files after every 2 view/browser/search operations to prevent losing multimodal information; read the plan before major decisions to keep goals in the attention window; update status (in_progress to complete) and log errors/files after completing any phase; log every error encountered in a structured table (error, attempt, resolution) to build knowledge and avoid repetition; and never repeat a failed action - mutate the approach instead.

The 3-strike error protocol escalates systematically: attempt 1 diagnoses and applies a targeted fix, attempt 2 tries a genuinely different approach or tool (never repeating the exact same failing action), attempt 3 questions assumptions and considers updating the plan, and after three failures the agent escalates to the user with what was tried and the specific error. A read-vs-write decision matrix covers six situations (don't re-read a just-written file since it's still in context; write findings immediately after viewing an image/PDF or receiving browser data since those don't persist; read the plan when starting a new phase, after an error, or when resuming after a gap). A 5-question reboot test (where am I, where am I going, what's the goal, what have I learned, what have I done) validates that context management is solid by mapping each question to its answer source file.

Provides helper scripts (init-session.sh to initialize all planning files, check-complete.sh to verify all phases are done) and lists anti-patterns to avoid: using ephemeral to-do tracking instead of a persistent file, stating goals once and forgetting them, hiding errors and silently retrying, stuffing everything into context instead of files, executing before planning, repeating failed actions, and creating planning files in the skill directory instead of the project.

Templates and reference scripts live in the skill's plugin directory (${CLAUDE_PLUGIN_ROOT}/templates/), while the actual working planning files are created in the user's project directory alongside the code being worked on.

Agents and developers working through long, multi-step, or research-heavy tasks who need durable state tracking across many tool calls and context resets rather than relying on in-context memory alone.

### Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |