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):

1. task_plan.md: The master plan. Tracks phases, specific tasks, and their completion status.
2. findings.md: The knowledge base. Stores lessons learned, decisions made, and technical details discovered.
3. 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]
- [Architecture]: [Description]

## 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: ...