Planning with Files

This skill implements a persistent memory workflow using three markdown files. This allows you to handle complex, multi-step tasks without losing context or forgetting goals.

The 3-File Pattern

For any complex task, you must maintain these three files in the root of the project (or a specific plans/ directory if preferred by the user):

• task_plan.md : The master plan. Tracks phases, specific tasks, and their completion status.

• findings.md : The knowledge base. Stores lessons learned, decisions made, and technical details discovered.

• progress.md : The session log. A chronological record of actions taken, results observed, and thoughts.

When to Use

• When the user asks for "planning with files".

• When starting a complex feature or refactoring.

• When the task requires multiple tool calls and steps.

• When you need to "remember" things for future sessions.

Instructions

1. Initialization

At the start of a task, check if these files exist. If not, create them by copying from the templates in .claude/templates/ or using the content below.

• task_plan.md: Break down the user's request into high-level phases and granular tasks. Mark them as [ ] (pending).

• findings.md: Initialize with an empty structure for "Key Decisions" and "Technical Learnings".

• progress.md: Add a header for the current session (Date/Time).

2. Execution Loop

Before and after running tools, update the files:

• Update progress.md : specific actions you are about to take or have just taken. Record command outputs or test results briefly.

• Update findings.md : If you discover how a system works, a hidden bug, or make an architectural decision, record it here immediately.

• Update task_plan.md : When a sub-task is done, mark it [x] . If new tasks are discovered, add them.

3. Context Management

• Do not rely on your context window for long-term memory.

• Read task_plan.md to know "what's next".

• Read findings.md to know "how things work" or "what we decided".

• Read progress.md to know "what did I just do".

Templates

task_plan.md Template

Task Plan: [Task Name]

Status

• Phase 1: [Name]
  • Task 1.1
  • Task 1.2
• Phase 2: [Name]

Current Context

• Focus: [Current Focus]
• Blockers: [Any Blockers]

findings.md Template

Findings & Knowledge

Key Decisions

• [Date] [Decision]: [Rationale]

Technical Learnings

• [Tool/Library]: [How to use it / Gotchas]

Unresolved Questions

• [Question]?

progress.md Template

Progress Log

[YYYY-MM-DD HH:MM] Session Start

• Goal: [Goal for this session]

[HH:MM] Action

• executed: command
• result: success/fail
• thoughts: ...