Skill: yingcd/planning-with-files-from-github (version 1.0.0)

--- name: planning-with-files description: "This skill should be used when the user asks to start a complex task, research project, multi-step implementation, or any task expected to require more than 5 tool calls. Triggers: 'plan this', 'start planning', 'help me build', 'research and implement', 'complex task', '/plan'." metadata: { "openclaw": { "emoji": "📋", "version": "1.0.0", "author": "shannon/openclaw-port" } } --- # Planning with Files Manus-style persistent markdown planning. Filesystem = long-term memory. Context window = working RAM. ## Core Principle ``` Context Window = RAM (volatile, limited) Filesystem = Disk (persistent, unlimited) → Anything important MUST be written to disk. ``` ## When to Use - Multi-step tasks (3+ phases or 5+ tool calls) - Research + implementation tasks - Tasks that span multiple sessions - Any task where goal-drift is a risk Skip for: single-file edits, quick lookups, simple questions. ## Session Start Protocol **ALWAYS do this first — no exceptions:** 1. Run the init script to create the three planning files: ``` exec: bash {baseDir}/scripts/init-session.sh "<task description>" ``` 2. Fill in the `## Goal` section in `task_plan.md` with the full task description. 3. Break the task into 3–7 phases and add them under `## Phases`. 4. Confirm files exist before proceeding. If exec is not available, create the three files manually using the templates in `{baseDir}/templates/`. ## The Three Files ### task_plan.md — Goal tracker (MOST IMPORTANT) - Created at session start, never deleted - Re-read before every major decision - Update when: phase completes, decision made, error encountered ### findings.md — Knowledge store - Research results, discoveries, technical decisions - **2-Action Rule**: after every 2 view/search/fetch operations → update findings.md immediately ### progress.md — Session log - Actions taken, test results, errors encountered - Append-only; never rewrite history ## Work Loop ``` BEFORE every major action: → Re-read task_plan.md (keeps goal in attention) EVERY 2 view/search/fetch operations: → Save key findings to findings.md NOW AFTER completing a phase: → Update phase status in task_plan.md to "complete" → Append phase summary to progress.md WHEN an error occurs: → Log it in task_plan.md under ## Errors table → Never repeat the same failing action BEFORE stopping: → Run: exec bash {baseDir}/scripts/check-complete.sh → Only stop if all phases show "complete" ``` ## File Update Rules | Trigger | File to update | Section | |---------|---------------|---------| | Start task | task_plan.md | Goal + Phases | | 2nd research op | findings.md | Key Findings | | Make decision | findings.md | Technical Decisions | | Phase done | task_plan.md | Phase status → complete | | Phase done | progress.md | Phase summary | | Error | task_plan.md | Errors table | | Test result | progress.md | Test Results | ## Error Recovery Protocol ``` ATTEMPT 1: Diagnose & Fix → Read error carefully → identify root cause → targeted fix ATTEMPT 2: Alternative Approach → Same error? Try different tool/library/method → NEVER repeat the exact same failing action ATTEMPT 3: Broader Rethink → Question assumptions → search for solutions → update plan AFTER 3 FAILURES: → Escalate to user: explain what was tried, share the error, ask for guidance ``` ## Completion Verification Before telling the user the task is done: 1. Run `exec bash {baseDir}/scripts/check-complete.sh` 2. If any phase is NOT "complete" → continue working 3. Only deliver result when all phases are checked off ## Session Recovery If context was cleared (e.g., `/clear`), resume by: 1. Reading `task_plan.md` to restore goal and phase status 2. Reading `progress.md` to see what was done 3. Reading `findings.md` to restore research context 4. Continuing from the first incomplete phase ## Key Principles - **Plan is Required**: Never start a complex task without `task_plan.md` - **Files are Memory**: Context is volatile. Filesystem is permanent. Write important things down. - **Never Repeat Failures**: Track what was tried. Mutate the approach. - **Error Recovery = Agentic Behavior**: How you handle failures defines task quality. - **Re-read Before Deciding**: Attention manipulation — keep the goal visible.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (MEDIUM)