planning-with-files

Use file-based planning: write the goal, phases, and decisions to a task_plan.md file on disk and re-read it before major decisions. This keeps goals in the model's attention window even after dozens of tool calls.

It creates three markdown files in your project root: task_plan.md for phases and decisions, findings.md for research discoveries, and progress.md for session logs and test results. Templates for each are included in the skill's templates directory.

Yes. The skill includes a session-catchup.py script that detects unsynced context from a previous session. Combined with git diff and the existing planning files, the agent reconstructs state and continues from the current phase.

Skip it for simple questions, single-file edits, and quick lookups. The overhead of creating and maintaining three planning files only pays off for tasks with three or more steps or many tool calls.

On the first failure, diagnose and apply a targeted fix. On the second, try a different method or tool. On the third, rethink assumptions and update the plan. After three failures, escalate to the user with the specific error.