Planning

AI Maestro Planning Skill

The Problem This Solves: EXECUTION

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

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):

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

The 5-Question Reboot

Lost? Answer these questions:

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

Integration with Memory Skill

Planning and Memory solve different problems:

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.