planning-with-files

• **Templates and scripts** are relative to this installed SKILL.md. Plugin installs also expose them under ${CLAUDE_PLUGIN_ROOT}/.
• **Your planning files** go in **the selected task directory in your project**

| Location | What Goes There |

|----------|-----------------|

| Installed skill or plugin directory | Templates, scripts, reference docs |

| Selected task directory (project root in legacy mode) | task_plan.md, findings.md, progress.md |

Quick Start

Before a complex task:

1. **Resolve or initialize the task directory.** Reuse the selected plan when resuming. For a separate task, run scripts/init-session.sh "Task Name" and use the printed PLAN_ID to pin its host.

2. **Create missing planning files only.** Use templates/task_plan.md (templates/task_plan.md), templates/findings.md (templates/findings.md), and templates/progress.md (templates/progress.md) in that directory. Preserve existing work.

3. **Re-read the selected plan before decisions.** Update progress after each phase.

4. **Assign one plan owner.** The orchestrator owns task_plan.md and shared summaries. Workers report through their own ledgers or assigned files; they do not independently rewrite the shared planning files.

> Planning files belong to the selected task directory in the project. The installation directory contains the scripts and templates.

The Core Pattern

Context Window = RAM (volatile, limited)
Filesystem = Disk (persistent, unlimited)

→ Anything important gets written to disk.

File Purposes

| File | Purpose | When to Update |

|------|---------|----------------|

| task_plan.md | Phases, progress, decisions | After each phase |

| findings.md | Research, discoveries | After ANY discovery |

| progress.md | Session log, test results | Throughout session |

Critical Rules

### 1. Create Plan First

Never start a complex task without task_plan.md. Non-negotiable.

### 2. The 2-Action Rule

> "After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files."

This prevents visual/multimodal information from being lost.

### 3. Read Before Decide

Before major decisions, read the plan file. This keeps goals in your attention window.

### 4. Update After Act

After completing any phase:

• Mark phase status: in_progress → complete
• Log any errors encountered
• Note files created/modified

### 5. Log ALL Errors

Every error goes in the plan file. This builds knowledge and prevents repetition.

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created default config |
| API timeout | 2 | Added retry logic |

### 6. Never Repeat Failures

if action_failed:
    next_action != same_action

Track what you tried. Mutate the approach.

### 7. Continue After Completion

When all phases are done but the user requests additional work:

• Add new phases to task_plan.md (e.g., Phase 6, Phase 7)
• Log a new session entry in progress.md
• Continue the planning workflow as normal

The 3-Strike Error Protocol

ATTEMPT 1: Diagnose & Fix
  → Read error carefully
  → Identify root cause
  → Apply targeted fix

ATTEMPT 2: Alternative Approach
  → Same error? Try different method
  → Different tool? Different library?
  → NEVER repeat exact same failing action

ATTEMPT 3: Broader Rethink
  → Question assumptions
  → Search for solutions
  → Consider updating the plan

AFTER 3 FAILURES: Escalate to User
  → Explain what you tried
  → Share the specific error
  → Ask for guidance

Read vs Write Decision Matrix

| Situation | Action | Reason |

|-----------|--------|--------|

| Just wrote a file | DON'T read | Content still in context |

| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |

| Browser returned data | Write to file | Screenshots don't persist |

| Starting new phase | Read plan/findings | Re-orient if context stale |

| Error occurred | Read relevant file | Need current state to fix |

| Resuming after gap | Read all planning files | Recover state |

The 5-Question Reboot Test

If you can answer these, your context management is solid:

| Question | Answer Source |

|----------|---------------|

| Where am I? | Current phase in task_plan.md |

| Where am I going? | Remaining phases |

| What's the goal? | Goal statement in plan |

| What have I learned? | findings.md |

| What have I done? | progress.md |

When to Use This Pattern

**Use for:**

• Multi-step tasks (3+ steps)
• Research tasks
• Building/creating projects
• Tasks spanning many tool calls
• Anything requiring organization

**Skip for:**

• Simple questions
• Single-file edits
• Quick lookups

Templates

Copy these templates to start:

• templates/task_plan.md (templates/task_plan.md) — Phase tracking
• templates/findings.md (templates/findings.md) — Research storage
• templates/progress.md (templates/progress.md) — Session logging

Scripts

Helper scripts for automation:

• scripts/init-session.sh — Initialize planning files. With a name arg, creates an isolated plan under .planning/YYYY-MM-DD-<slug>/ for parallel task workflows. Without args, writes task_plan.md at project root (legacy mode, backward-compatible).
• scripts/set-active-plan.sh — Switch the active plan pointer (.planning/.active_plan). Run with a plan ID to switch; run without args to show which plan is current.
• scripts/resolve-plan-dir.sh — Resolve the active plan directory. A set $PLAN_ID is a binding: it resolves or resolution stops, never another plan (issue #237). With no $PLAN_ID, multiple named plans refuse sele