23blocks-os/planning

AI Maestro Planning Skill

The Problem This Solves: EXECUTION

This skill solves the execution problem - losing focus during complex tasks:

| Problem | Symptom | This Skill Fixes It | |---------|---------|---------------------| | Goal drift | Forgot original objective after 50 tool calls | Re-read plan before decisions | | Lost progress | Can't remember what phase I'm in | Phase tracking in task_plan.md | | Repeated errors | Make same mistake twice | Error log prevents repetition | | Session loss | Can't resume after /clear | Planning files persist on disk |

Note: This is different from the Memory skill (which solves recall of past conversations). Planning solves staying focused NOW.

---

Core Principle

Context Window = RAM (volatile, limited, fast)
Filesystem = Disk (persistent, unlimited, explicit read required)

Anything important gets written to disk.

---

Output Directory

Planning output files (task_plan.md, findings.md, progress.md) should be written to:

1. The directory specified by the AIMAESTRO_PLANNING_DIR environment variable (if set)
2. Otherwise, docs_dev/ in the current project root
3. Create the directory if it does not exist

Do NOT write planning files to the project root — use docs_dev/ to avoid cluttering the project.

---

The 3-File Pattern

Create these files in docs_dev/ (not the project root or the skill directory):

| File | Purpose | Update When | |------|---------|-------------| | task_plan.md | Goals, phases, decisions, errors | After each phase | | findings.md | Research, discoveries, resources | During research | | progress.md | Session log, test results | Throughout session |

---

Quick Start

Before any complex task (3+ steps):

# 1. Determine output directory
PLAN_DIR="${AIMAESTRO_PLANNING_DIR:-docs_dev}"
mkdir -p "$PLAN_DIR"

# 2. Create planning files from templates
cat ~/.claude/skills/planning/templates/task_plan.md > "$PLAN_DIR/task_plan.md"
cat ~/.claude/skills/planning/templates/findings.md > "$PLAN_DIR/findings.md"
cat ~/.claude/skills/planning/templates/progress.md > "$PLAN_DIR/progress.md"

# 3. Edit task_plan.md with your specific goal and phases

Then follow the rules below.

---

The 6 Rules

Rule 1: Create Plan First

NEVER start a complex task without creating task_plan.md.

Before writing any code or making any changes:

1. Create task_plan.md with clear goal
2. Break work into phases
3. List key questions to answer

Rule 2: Read Before Decide

Before any major decision, re-read the plan:

cat "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md" | head -50

This refreshes your goals in the context window, preventing drift.

Rule 3: Update After Act

After completing any phase:

• Mark phase as [x] complete
• Update status section
• Log any errors encountered
• Note files created/modified

Rule 4: The 2-Action Rule

After every 2 search/view/browse operations, immediately save key findings to findings.md.

Visual content (screenshots, PDFs, browser results) doesn't persist in context. Write it down NOW.

Rule 5: Log ALL Errors

Every error goes in task_plan.md:

## Errors Encountered
| Error | Attempt | Resolution |
|-------|---------|------------|
| FileNotFoundError | 1 | Created missing config |
| API timeout | 2 | Added retry with backoff |

This prevents repeating the same mistakes.

Rule 6: Never Repeat Failures

if action_failed:
    next_action != same_action

After a failure, CHANGE your approach. Don't retry the exact same thing.

---

The 3-Strike Protocol

Attempt 1: Diagnose & Fix

• Read error carefully
• Identify root cause
• Apply targeted fix

Attempt 2: Alternative Approach

• Same error? Try different method
• Consider different tools/libraries
• NEVER repeat exact failing action

Attempt 3: Broader Rethink

• Question assumptions
• Search for similar issues
• Update task plan with learnings

After 3 Failures: Escalate

• Explain all approaches tried
• Share specific error messages
• Ask user for guidance

---

When to Read vs Write

| Situation | Action | Why | |-----------|--------|-----| | Just wrote a file | DON'T read | Content is in context | | Viewed image/PDF | Write findings NOW | Visual content doesn't persist | | Browser returned data | Write to findings.md | Screenshots don't persist | | Starting new phase | Read task_plan.md | Re-orient from plan | | Error occurred | Read relevant file | Need current state | | Resuming after gap | Read ALL planning files | Recover context |

---

The 5-Question Reboot

Lost? Answer these questions:

| Question | Find Answer In | |----------|----------------| | Where am I? | Current phase in task_plan.md | | Where am I going? | Remaining phases in task_plan.md | | What's the goal? | Goal section in task_plan.md | | What have I learned? | findings.md | | What have I done? | progress.md |

---

When to Use This Skill

USE for:

• Multi-step tasks (3+ steps)
• Research projects
• Building features
• Tasks requiring >5 tool calls
• Anything needing organization

SKIP for:

• Simple questions
• Single-file edits
• Quick lookups
• Trivial changes

---

Anti-Patterns

| DON'T | DO Instead | |-------|------------| | Use TodoWrite for complex tasks | Create task_plan.md file | | State goals once and forget | Re-read plan before decisions | | Hide errors and retry | Document errors in plan | | Stuff everything in context | Store large content in files | | Start executing immediately | Create plan FIRST | | Repeat failed actions | Track attempts, change approach |

---

Integration with Memory Skill

Planning and Memory solve different problems:

| Skill | Problem | Timescale | |-------|---------|-----------| | Memory | "What did we discuss last week?" | Days/weeks/months | | Planning | "What am I supposed to do next?" | Minutes/hours |

Use BOTH for complex work:

1. Memory - Search for past decisions and context
2. Planning - Stay focused during execution

---

Templates

Templates are in ~/.claude/skills/planning/templates/:

• task_plan.md - Phase and progress tracking
• findings.md - Research and discoveries
• progress.md - Session logging

Note: The template path depends on how the skill was installed:

• User scope (global): ~/.claude/skills/planning/templates/
• Project scope (local): <project>/.claude/skills/planning/templates/

Copy to docs_dev/ and customize.

---

Example Workflow

User: "Build a new authentication system"

1. CREATE PLAN
   - Copy templates to docs_dev/
   - Define goal: "Implement JWT authentication"
   - Break into phases: Research, Design, Implement, Test, Document

2. EXECUTE PHASE 1 (Research)
   - Search memory: memory-search.sh "authentication"
   - Search docs: docs-search.sh "auth patterns"
   - Write findings to findings.md
   - Mark Phase 1 complete in task_plan.md

3. EXECUTE PHASE 2 (Design)
   - READ task_plan.md (refresh goals)
   - READ findings.md (recall research)
   - Design approach, document decisions
   - Mark Phase 2 complete

4. CONTINUE...
   - Always read plan before major decisions
   - Always update after completing phases
   - Always log errors

---

Troubleshooting

Templates not found:

ls ~/.claude/skills/planning/templates/

If missing, reinstall the skill or copy from AI Maestro repo.

Forgot the goal:

cat "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md" | head -20

Lost track of progress:

grep -E "^\s*-\s*\[" "${AIMAESTRO_PLANNING_DIR:-docs_dev}/task_plan.md"

Shows all checkboxes and their status.