Pi planning with files

--- name: pi-planning-with-files description: Implements Manus-style file-based planning to organize and track progress on complex tasks. Creates task_plan.md, findings.md, and progress.md. Use when asked to plan out, break down, or organize a multi-step project, research task, or any work requiring 5+ tool calls. Supports automatic session recovery after /clear. --- # Planning with Files Work like Manus: Use persistent markdown files as your "working memory on disk." ## FIRST: Restore Context Before doing anything else, check if planning files exist and read them: 1. If task_plan.md exists, read task_plan.md, progress.md, and findings.md immediately. 2. The extension automatically checks for unsynced context from a previous session. If catchup report shows unsynced context: 1. Run git diff --stat to see actual code changes 2. Read current planning files 3. Update planning files based on catchup + git diff 4. Then proceed with task ## Important: Where Files Go - Templates are in templates/ inside this skills - Your planning files go in your project directory | Location | What Goes There | |----------|-----------------| | skills directory | Templates, scripts, reference docs | | Your project directory | task_plan.md, findings.md, progress.md | ## Quick Start Before ANY complex task: 1. **Create task_plan.md : Use [templates/task_plan.md](templates/task_plan.md) as reference 2. Create findings.md : Use [templates/findings.md](templates/findings.md) as reference 3. Create progress.md : Use [templates/progress.md](templates/progress.md) as reference 4. Re-read plan before decisions : Refreshes goals in attention window 5. Update after each phase : Mark complete, log errors > Note:** Planning files go in your project root, not the skills installation folder. ## 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. `markdown ## 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