Planning with Files Skill

Operator Context

Hardcoded Behaviors (Always Apply)

• CLAUDE.md Compliance: Read and follow repository CLAUDE.md before starting any planned work
• Over-Engineering Prevention: Plan only the phases needed. No speculative phases, no "future-proofing" empty sections
• Plan Before Execute: NEVER start complex work without creating

  task_plan.md

  first
• Re-Read Before Decide: Read plan file before every major decision to combat context drift
• Update After Act: Mark phases complete and update status immediately after each phase
• Store, Don't Stuff: Large outputs go to files, not context. Keep only file paths in working memory

Default Behaviors (ON unless disabled)

• 3-File Pattern: Create

  task_plan.md

  ,

  notes.md

  , and deliverable file for non-trivial tasks
• Error Logging: Record all errors in the "Errors Encountered" section of plan file
• Phase Checkboxes: Use

  - [ ]

  /

  - [x]

  for phase tracking
• Status Line: Maintain a "Currently in Phase X" status at bottom of plan
• Findings Synthesis: Consolidate research notes into categorized findings before generating deliverables
• Cleanup at Completion: Remove temporary scratch files, keep plan and deliverable

Optional Behaviors (OFF unless enabled)

• Timestamp Entries: Add

  [YYYY-MM-DD]

  timestamps to errors and decisions
• Git Integration: Create commits at phase boundaries
• Parallel Research: Launch multiple search queries simultaneously in research phase

What This Skill CAN Do

• Structure complex tasks into trackable phases with file-based persistence
• Maintain focus across long sessions by re-reading goals into attention window
• Store and synthesize research findings across multiple sources
• Recover from context drift by grounding decisions in written plans
• Preserve failure traces for error recovery and institutional knowledge

What This Skill CANNOT Do

• Replace domain-specific skills (use systematic-debugging for bugs, systematic-refactoring for refactoring)
• Execute without a written plan for complex tasks
• Store sensitive data (credentials, tokens) in plan files
• Skip the re-read step before major decisions

Instructions

Phase 1: CREATE PLAN

• 3+ steps or phases required → Plan needed
• Research or information gathering involved → Plan needed
• Task spans multiple files or systems → Plan needed
• Simple lookup or single edit → Skip planning

task_plan.md

# Task Plan: [Brief Description]

## Goal
[One sentence describing the end state]

## Phases
- [ ] Phase 1: [First phase]
- [ ] Phase 2: [Second phase]
- [ ] Phase 3: [Third phase]
- [ ] Phase 4: [Review and deliver]

## Key Questions
1. [Question to answer before proceeding]

## Decisions Made
- [Decision]: [Rationale]

## Errors Encountered
- [Error]: [Resolution]

## Status
**Currently in Phase 1** - Creating plan

task_plan.md

Phase 2: RESEARCH AND GATHER

task_plan.md

notes.md

# Notes: [Topic]

## Sources
### Source 1: [Name]
- Key points:
  - [Finding]
  - [Finding]

## Synthesized Findings
### [Category]
- [Finding with context]

notes.md

Phase 3: EXECUTE

task_plan.md

notes.md

Phase 4: VERIFY AND DELIVER

• All phases marked

  [x]

• All key questions answered
• Deliverable matches stated goal
• Errors section documents any issues encountered

task_plan.md

Examples

Example 1: Research Task

1. Create

   task_plan.md

   with goal and 4 phases (CREATE PLAN)
2. Search sources, store findings in

   notes.md

   (RESEARCH)
3. Re-read notes, write

   morning_exercise_summary.md

   (EXECUTE)
4. Verify summary covers all key questions, deliver (VERIFY) Result: Structured summary grounded in documented research

Example 2: Multi-File Refactoring Plan

1. Create

   task_plan.md

   with migration phases (CREATE PLAN)
2. Inventory endpoints, dependencies, store in

   notes.md

   (RESEARCH)
3. Write

   migration_plan.md

   with ordered steps (EXECUTE)
4. Verify all endpoints covered, deliver plan (VERIFY) Result: Actionable migration plan with nothing missed

Error Handling

Error: "Context Drift — Forgot Original Goal"

1. Immediately read

   task_plan.md

2. Compare current work against stated goal
3. Correct course if diverged
4. Increase re-read frequency for remainder of task

Error: "Plan Becomes Stale or Inaccurate"

1. Update plan with new information and revised phases
2. Log the change in Decisions Made with rationale
3. Continue from updated plan

Error: "Notes File Too Large for Context"

1. Add a "Summary" section at top of

   notes.md

   with key takeaways
2. Reference specific sections by heading when needed
3. Read only relevant sections, not entire file

Anti-Patterns

Anti-Pattern 1: Executing Without a Plan

task_plan.md

Anti-Pattern 2: Writing Plan but Never Re-Reading

task_plan.md

Anti-Pattern 3: Stuffing Context Instead of Storing

notes.md

Anti-Pattern 4: Over-Planning Simple Tasks

References

• Anti-Rationalization - Prevents shortcut rationalizations
• Verification Checklist - Pre-completion checks
• Gate Enforcement - Phase transition enforcement

Domain-Specific Anti-Rationalization

task_plan.md

notes.md