# Planner Skill - Metis, Titan of Wisdom

Agentic planning and execution for complex multi-step tasks.

Metis was the Titan of wisdom, deep thought, and cunning counsel.
She helped Zeus defeat Kronos through careful strategic planning.

## What This Does

Transforms Familiar from a reactive assistant into a **proactive agent** that can:

- Decompose complex goals into steps
- Understand dependencies between steps  
- Execute plans with monitoring
- Self-correct when steps fail
- Learn from successful executions
- Chain tools automatically

## The Agentic Loop

```
Goal → Decompose → Plan → Execute → Verify → Adapt
         ↑                              |
         └──────── Self-correct ←───────┘
```

## Quick Start

### Simple Goal
```
"Accomplish: Research competitors and create a summary report"
```

### Create Plan First
```
"Create a plan to migrate our email list to the new system"
```

### Execute Later
```
"Execute plan abc123"
```

## How Plans Work

### 1. Decomposition
The LLM analyzes your goal and breaks it into discrete steps:

```
Goal: "Prepare board meeting materials"
  ↓
Steps:
  1. Search emails for agenda items
  2. Pull financial data from last quarter
  3. Generate summary document
  4. Create presentation slides
  5. Send to board members
```

### 2. Dependency Analysis
Steps are ordered based on what depends on what:

```
[1] Search emails (no dependencies)
[2] Pull financial data (no dependencies)  
[3] Generate summary (depends on 1, 2)
[4] Create slides (depends on 3)
[5] Send to board (depends on 4)
```

### 3. Parallel Execution
Independent steps run concurrently:

```
[1] Search emails ──┐
                    ├──→ [3] Generate summary → [4] Slides → [5] Send
[2] Pull data ──────┘
```

### 4. Self-Correction
When a step fails, the planner:
1. Analyzes the error
2. Decides: RETRY, MODIFY, SKIP, REPLAN, or ABORT
3. Adapts and continues

## Step Types

### Tool
Call any Familiar tool:
```json
{
  "action_type": "tool",
  "action_config": {
    "tool": "search_knowledge",
    "input": {"query": "quarterly results"}
  }
}
```

### Chat
Ask the LLM to generate or analyze:
```json
{
  "action_type": "chat",
  "action_config": {
    "prompt": "Summarize: {{step_1.result}}"
  }
}
```

### Condition
Branch based on results:
```json
{
  "action_type": "condition",
  "condition": "{{step_1.result.count}} > 10",
  "if_true": "step_detailed",
  "if_false": "step_simple"
}
```

### Human
Wait for user input:
```json
{
  "action_type": "human",
  "action_config": {
    "prompt": "Please review and approve"
  }
}
```

## Template Variables

Reference previous step outputs:

| Variable | Description |
|----------|-------------|
| `{{step_id.result}}` | Output from a previous step |
| `{{context.key}}` | Value from plan context |

Example:
```
Step 1 outputs: {"emails": [...], "count": 5}
Step 2 prompt: "Summarize these {{step_1.result.count}} emails"
```

## Self-Correction

When steps fail, the planner reflects and decides:

| Action | Description |
|--------|-------------|
| RETRY | Try again (transient error) |
| MODIFY | Change parameters and retry |
| SKIP | Skip if not critical |
| REPLAN | Create new steps to work around |
| ABORT | Goal cannot be achieved |

Example failure flow:
```
Step "fetch_url" fails with timeout
  → Reflect: Network might be slow
  → Decision: RETRY with longer timeout
  → Retry succeeds
  → Continue plan
```

## Learning System

Successful plans are recorded as patterns:

```
Goal: "prepare monthly report"
  → Pattern: .*prepare.*monthly.*report.*
  → Steps: [gather_data, analyze, format, send]
  → Success rate: 95% (20 uses)
```

Future similar goals can reuse learned patterns.

## Example Workflows

### Research and Report
```
"Accomplish: Research AI safety developments this week and write a summary"

Plan:
1. [tool] web_search: "AI safety news this week"
2. [tool] web_fetch: Get full articles
3. [chat] Summarize key developments
4. [tool] add_document: Save to knowledge base
5. [chat] Generate final report
```

### Email Campaign
```
"Accomplish: Send personalized thank-you emails to this month's donors"

Plan:
1. [tool] search_donors: This month's donations
2. [parallel]
   - [tool] get_template: Thank you template
   - [chat] Generate personalization notes
3. [tool] send_emails: Merge and send
4. [tool] log_activity: Record in CRM
```

### Meeting Prep
```
"Accomplish: Prepare for tomorrow's board meeting"

Plan:
1. [tool] calendar_search: Get meeting details
2. [parallel]
   - [tool] search_knowledge: Past board notes
   - [tool] triage_inbox: Board-related emails
3. [chat] Generate agenda summary
4. [tool] create_document: Meeting brief
5. [tool] notify: Send reminder to attendees
```

## Tools

| Tool | Description |
|------|-------------|
| accomplish | Create and execute plan in one step |
| create_plan | Create plan without executing |
| execute_plan | Execute existing plan |
| list_plans | Show all plans |
| get_plan | Plan details and status |
| cancel_plan | Cancel running plan |
| resume_plan | Resume paused/failed plan |
| learnings | Show learned patterns |

## Plan Status

| Status | Description |
|--------|-------------|
| draft | Plan created but not validated |
| ready | Plan validated, ready to run |
| running | Currently executing |
| paused | Stopped, can be resumed |
| completed | All steps finished successfully |
| failed | Critical step failed |
| cancelled | Manually cancelled |

## Configuration

Plans have these settings:

```json
{
  "max_iterations": 50,
  "allow_parallel": true,
  "auto_retry": true,
  "require_approval": false
}
```

## File Locations

- Plans: `~/.familiar/data/planner/plans/`
- Learnings: `~/.familiar/data/planner/learnings.json`
- Executions: `~/.familiar/data/planner/executions/`

## Best Practices

1. **Be specific** - "Research Q4 competitor pricing" beats "look at competitors"

2. **Provide context** - Include relevant details:
   ```
   "Accomplish: Prepare grant report"
   context: {"grant_name": "Ford Foundation", "period": "Q3 2024"}
   ```

3. **Start with create_plan** - Review before executing:
   ```
   "Create a plan to reorganize the document archive"
   # Review steps...
   "Execute plan xyz123"
   ```

4. **Use resume** - Don't restart failed plans:
   ```
   "Resume plan xyz123 from step_3"
   ```

## Integration

The planner automatically discovers all available tools.
Any skill you add becomes available for planning.

```
New skill: "twitter" with tools [post_tweet, search_tweets]
  ↓
Planner can now include Twitter in plans:
  "Accomplish: Monitor mentions and respond to questions"
```

## Limitations

- Plans are generated by LLM, quality depends on goal clarity
- Complex branching logic may need manual plan editing
- Human input steps require interactive mode
- Very long plans (50+ steps) may hit iteration limits
