{"id":"planning-with-files-4cced1","name":"planning-with-files","summary":"Manusスタイルの永続ファイルベースの計画はAIコーディングエージェント向けで、task_plan.md、findings.md、progress.md をディスクに保持し、コンテキストの喪失や/クリアに耐えて作業が残ります。","body":"# Planning with Files\n\nWork like Manus: Use persistent markdown files as your \"working memory on disk.\"\n\n## FIRST: Check for Previous Session (v2.2.0)\n\n**Before starting work**, check for unsynced context from a previous session:\n\n```bash\n# Linux/macOS (auto-detects python3 or python)\n$(command -v python3 || command -v python) .cursor/skills/planning-with-files/scripts/session-catchup.py \"$(pwd)\"\n```\n\n```powershell\n# Windows PowerShell\npython \"$env:USERPROFILE\\.cursor\\skills\\planning-with-files\\scripts\\session-catchup.py\" (Get-Location)\n```\n\nIf catchup report shows unsynced context:\n1. Run `git diff --stat` to see actual code changes\n2. Read current planning files\n3. Update planning files based on catchup + git diff\n4. Then proceed with task\n\n## Important: Where Files Go\n\n- **Templates** are in `.cursor/skills/planning-with-files/templates/`\n- **Your planning files** go in **your project directory**\n\n| Location | What Goes There |\n|----------|-----------------|\n| Skill directory (`.cursor/skills/planning-with-files/`) | Templates, scripts, reference docs |\n| Your project directory | `task_plan.md`, `findings.md`, `progress.md` |\n\n## Quick Start\n\nBefore ANY complex task:\n\n1. **Create `task_plan.md`** — Use [templates/task_plan.md](templates/task_plan.md) as reference\n2. **Create `findings.md`** — Use [templates/findings.md](templates/findings.md) as reference\n3. **Create `progress.md`** — Use [templates/progress.md](templates/progress.md) as reference\n4. **Re-read plan before decisions** — Refreshes goals in attention window\n5. **Update after each phase** — Mark complete, log errors\n\n> **Note:** Planning files go in your project root, not the skill installation folder.\n\n## The Core Pattern\n\n```\nContext Window = RAM (volatile, limited)\nFilesystem = Disk (persistent, unlimited)\n\n→ Anything important gets written to disk.\n```\n\n## File Purposes\n\n| File | Purpose | When to Update |\n|------|---------|----------------|\n| `task_plan.md` | Phases, progress, decisions | After each phase |\n| `findings.md` | Research, discoveries | After ANY discovery |\n| `progress.md` | Session log, test results | Throughout session |\n\n## Critical Rules\n\n### 1. Create Plan First\nNever start a complex task without `task_plan.md`. Non-negotiable.\n\n### 2. The 2-Action Rule\n> \"After every 2 view/browser/search operations, IMMEDIATELY save key findings to text files.\"\n\nThis prevents visual/multimodal information from being lost.\n\n### 3. Read Before Decide\nBefore major decisions, read the plan file. This keeps goals in your attention window.\n\n### 4. Update After Act\nAfter completing any phase:\n- Mark phase status: `in_progress` → `complete`\n- Log any errors encountered\n- Note files created/modified\n\n### 5. Log ALL Errors\nEvery error goes in the plan file. This builds knowledge and prevents repetition.\n\n```markdown\n## Errors Encountered\n| Error | Attempt | Resolution |\n|-------|---------|------------|\n| FileNotFoundError | 1 | Created default config |\n| API timeout | 2 | Added retry logic |\n```\n\n### 6. Never Repeat Failures\n```\nif action_failed:\n    next_action != same_action\n```\nTrack what you tried. Mutate the approach.\n\n## The 3-Strike Error Protocol\n\n```\nATTEMPT 1: Diagnose & Fix\n  → Read error carefully\n  → Identify root cause\n  → Apply targeted fix\n\nATTEMPT 2: Alternative Approach\n  → Same error? Try different method\n  → Different tool? Different library?\n  → NEVER repeat exact same failing action\n\nATTEMPT 3: Broader Rethink\n  → Question assumptions\n  → Search for solutions\n  → Consider updating the plan\n\nAFTER 3 FAILURES: Escalate to User\n  → Explain what you tried\n  → Share the specific error\n  → Ask for guidance\n```\n\n## Read vs Write Decision Matrix\n\n| Situation | Action | Reason |\n|-----------|--------|--------|\n| Just wrote a file | DON'T read | Content still in context |\n| Viewed image/PDF | Write findings NOW | Multimodal → text before lost |\n| Browser returned data | Write to file | Screenshots don't persist |\n| Starting new phase | Read plan/findings | Re-orient if context stale |\n| Error occurred | Read relevant file | Need current state to fix |\n| Resuming after gap | Read all planning files | Recover state |\n\n## The 5-Question Reboot Test\n\nIf you can answer these, your context management is solid:\n\n| Question | Answer Source |\n|----------|---------------|\n| Where am I? | Current phase in task_plan.md |\n| Where am I going? | Remaining phases |\n| What's the goal? | Goal statement in plan |\n| What have I learned? | findings.md |\n| What have I done? | progress.md |\n\n## When to Use This Pattern\n\n**Use for:**\n- Multi-step tasks (3+ steps)\n- Research tasks\n- Building/creating projects\n- Tasks spanning many tool calls\n- Anything requiring organization\n\n**Skip for:**\n- Simple questions\n- Single-file edits\n- Quick lookups\n\n## Templates\n\nCopy these templates to start:\n\n- [templates/task_plan.md](templates/task_plan.md) — Phase tracking\n- [templates/findings.md](templates/findings.md) — Research storage\n- [templates/progress.md](templates/progress.md) — Session logging\n\n## Scripts\n\nHelper scripts for automation:\n\n- `scripts/init-session.sh` — Initialize all planning files\n- `scripts/check-complete.sh` — Verify all phases complete\n- `scripts/session-catchup.py` — Recover context from previous session (v2.2.0)\n\n## Advanced Topics\n\n- **Manus Principles:** See [reference.md](reference.md)\n- **Real Examples:** See [examples.md](examples.md)\n\n## Anti-Patterns\n\n| Don't | Do Instead |\n|-------|------------|\n| Use TodoWrite for persistence | Create task_plan.md file |\n| State goals once and forget | Re-read plan before decisions |\n| Hide errors and retry silently | Log errors to plan file |\n| Stuff everything in context | Store large content in files |\n| Start executing immediately | Create plan file FIRST |\n| Repeat failed actions | Track attempts, mutate approach |\n| Create files in skill directory | Create files in your project |","author":"@OthmanAdi","ownerProfile":null,"authorContacts":null,"sourceUrl":"https://github.com/OthmanAdi/planning-with-files/tree/master/.cursor/skills/planning-with-files","license":"MIT","category":"document","lang":"en","tokens":1416,"stars":0,"calls30d":2,"claimed":false,"visibility":"public","origin":"crawler","version":"0.1.0","createdAt":"2026-08-22","updatedAt":"2026-08-22","files":[{"path":"examples.md","size":4518,"sha256":"450355fac69e0fac93453b6c7383c8fb9ba3470662f6c8291080028f73ce00dc"},{"path":"reference.md","size":8455,"sha256":"8f7d9cfe1971c5a32f3e5edb63ddfad73a11cc7de19d5065a6ec75fd118c0fdb"},{"path":"scripts/attest-plan.ps1","size":5041,"sha256":"6d059c1306023c0e793a6eb43d0a5e8c928eb881f2253f08080506995c057724"},{"path":"scripts/attest-plan.sh","size":8771,"sha256":"fae1c8faf2c01da03d4673a909de1cb0fa9d1b582033b14b3dcd54be2b605974"},{"path":"scripts/check-complete.ps1","size":9919,"sha256":"51a99ef1b1d38710e9fb318771ea1ad326a32c5b4322b7ef19598e7fbea10d04"},{"path":"scripts/check-complete.sh","size":10085,"sha256":"4fb617e802e7b7ce0849dea1d46d194608d511e74c3d6b82e3653e150fd95724"},{"path":"scripts/init-session.ps1","size":6490,"sha256":"4d854b872b9255412fee506b2438029c58b9cb4edcbae4fd29a60732cc83a4f6"},{"path":"scripts/init-session.sh","size":11163,"sha256":"6580294356d670a80ac28fd9a6c38e65efa8f3899ed8ad340e2c9cd8154bfd42"},{"path":"scripts/inject-plan.sh","size":31507,"sha256":"f36056a6de18b2a0b51a9e98310edd37ee08a5ac37b8f7265a5eec71c63bc38d"},{"path":"scripts/ledger-summary.sh","size":6136,"sha256":"56030727eb67a82c04303b255123956e2abc5ce017bfe706115dc722155e8478"},{"path":"scripts/plan-doctor.sh","size":6857,"sha256":"9bdca6f1dc6bab9f9b5260476c014dacbf6af77dbed73611f72018e58114425f"},{"path":"scripts/resolve-plan-dir.ps1","size":4334,"sha256":"1302cfaec3fee85d65c84ccef521bae8a5f3a68d4c61abf8e5e720248ab5b2f2"},{"path":"scripts/resolve-plan-dir.sh","size":11015,"sha256":"031f1de0ff0605f9fd964682b080996bb1052257eef287ac76de22dc785ee97b"},{"path":"scripts/session-catchup.py","size":31548,"sha256":"6476fd9024d0cbb9bfb850119fd0beff7fb7cfab9c6683ce10e4cc8d830ce6de"},{"path":"scripts/set-active-plan.ps1","size":1645,"sha256":"31d99a29389cbfe0ab7c097729a7289ef622f261c3b70fd7712a43e2d37aece1"},{"path":"scripts/set-active-plan.sh","size":1505,"sha256":"72e3e2b3dcd9cb40018ebd86491f54deb84b540f723dd4a0e78ac47931c5db6c"},{"path":"templates/analytics_findings.md","size":3336,"sha256":"32273b4731fadf31a7e361f353eb6863d168c4c82374fe913bad2e393362fa43"},{"path":"templates/analytics_task_plan.md","size":3980,"sha256":"9a3489af0abcded777ce81913ef1049040f1cac27e956a5987dcb57d6a539feb"},{"path":"templates/findings.md","size":3561,"sha256":"b5e64d73704daefa8492356d2c2c67ffeb78d79d448b316c0a0debc9226ad785"},{"path":"templates/progress.md","size":4001,"sha256":"a2366167ed178bc4a3c1d72ec6c5f6ea9e38aed67c6f3dd2c1a8cbdb4cde76b6"},{"path":"templates/task_plan.md","size":4950,"sha256":"fef51835c7567d334c019f355a5794e9fe6124f49fcbe0e9e2694b7406ad2c37"}],"requires":{"mcp":[],"tools":["Read Write Edit Bash Glob Grep"]},"safety":{"flags":[{"code":"net.endpoints","kind":"exfiltration","excerpt":"docs.python.org, manus.im","message":"bundled scripts reach 2 external host(s)","severity":"warn"}],"scannedAt":"2026-08-22","hasScripts":true,"networkEndpoints":["docs.python.org","manus.im"]}}