planning-with-files

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

The session-catchup.py script scans the previous session transcript for messages after the last planning file update, then prints unsynced context. You run git diff --stat, read the planning files, and update them before continuing.

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

Skip it for simple questions, single-file edits, and quick lookups. The pattern is designed for tasks with three or more steps, research work, or anything spanning many tool calls where context loss is a real risk.

A PreToolUse hook re-reads task_plan.md before every tool call, so untrusted external content there gets repeatedly injected into context, amplifying prompt injection risk. Write web findings to findings.md instead.