# Wall-E Prompt Architecture: Intent-Driven Assembly

## Problem Statement

Wall-E's original system prompt used a one-size-fits-all approach: every query got the
same instruction block telling the model to "search memories MULTIPLE TIMES for ANY
question beyond small talk." A simple calendar query ("what's my schedule for tomorrow")
triggered unnecessary Slack/memory searches, burning 3+ minutes across multiple LLM
round-trips before the model ever called `calendar_events`.

### Root Causes

1. **Redundant search layers**: `buildRelevantLayer()` already pre-fetches context at
   prompt-build time, but the instruction layer told the model to search again at runtime.
2. **Hardcoded search examples**: The instruction block contained person-name examples
   that leaked into every query regardless of intent.
3. **No intent-to-toolchain mapping**: `classifyTopics()` only selected which context to
   inject — not which tools or instructions the model received.

## Architecture Overview

```
User message
     |
     v
classifyTopics() + classifyIntent()
     |
     v
Intent Category
     |
     +-- DIRECT_ACTION (calendar, weather, reminders, apps, shell, files)
     |        |
     |        v
     |   Minimal prompt: Core + Situational + Direct Instructions
     |   Filtered tools: only relevant tools (5-8)
     |   Limits: MAX_TURNS=3, TIMEOUT=30s
     |
     +-- KNOWLEDGE (people, work, opinions, history, Slack)
     |        |
     |        v
     |   Full prompt: Core + Relevant + Situational + Knowledge Instructions
     |   Full tool set (all tools)
     |   Limits: MAX_TURNS=8, TIMEOUT=120s
     |
     +-- CONVERSATIONAL (greetings, small talk, simple questions)
              |
              v
          Minimal prompt: Core + Light Instructions
          Minimal tools: think, remember_fact
          Limits: MAX_TURNS=2, TIMEOUT=15s
```

## Intent Categories

| Category | Topics | Behavior | Target Latency |
|----------|--------|----------|----------------|
| `direct_action` | calendar, weather, reminder, timer, app, shell, file | Call tool directly, format output | <10s |
| `knowledge` | people, work, slack, opinion, history | Pre-fetched context + optional search + think + respond | <30s |
| `conversational` | greeting, small talk, meta | Respond directly, minimal tools | <5s |

## Three Key Changes

### 1. Filter tool set per intent

Direct-action queries only see tools relevant to the action. This prevents the model
from choosing `search_memories` or `slack_search` when it should call `calendar_events`.

```
DIRECT_ACTION tools: calendar_events, calendar_create, web_fetch,
    reminder_create, notification, open_url, open_app, run_shell,
    read_file, write_file, search_files, glob, grep_files,
    applescript, screenshot, system_info, clipboard_read, clipboard_write

KNOWLEDGE tools: ALL tools (full set)

CONVERSATIONAL tools: think, remember_fact, search_memories (optional)
```

### 2. Skip `buildRelevantLayer` for direct-action queries

For direct actions, the model doesn't need pre-fetched memories or knowledge triples.
Skipping this saves:
- ~50-200ms of embedding computation
- ~50ms of FTS5/LIKE DB queries
- ~500-1500 tokens of system prompt space

### 3. Separate instruction blocks per intent

Each intent category gets its own instruction text. No instruction leakage between modes.

**Direct-action instructions:**
> "Call the appropriate tool directly. Respond with the formatted result.
>  Do NOT search memories. Do NOT use the think tool for straightforward output."

**Knowledge instructions:**
> "Relevant context is provided above. If it answers the question, respond directly.
>  If you need more information, use search_memories. Use the think tool to reason
>  through evidence before responding."

**Conversational instructions:**
> "Respond naturally. Keep it brief unless the user asks for more."

## Implementation Files

| File | Change |
|------|--------|
| `wall-e/context/topic-matcher.js` | Add `classifyIntent()` that maps topics to intent category |
| `wall-e/context/context-builder.js` | Accept intent; skip relevant layer for direct_action; select instruction block |
| `wall-e/chat.js` | Pass intent to buildSystemPrompt; filter tool set; set adaptive limits |

## Design Principles (from research)

1. **"Context is the bottleneck, not intelligence"** (Anthropic) — Don't re-search what
   the system prompt already provides.
2. **"Non-overlapping, purpose-specific tools"** (Context Engineering) — Don't offer tools
   that duplicate what the system prompt layer already did.
3. **"Semantic routing: deterministic before stochastic"** (Arize AI) — Use the topic
   classifier (deterministic) to route before asking the LLM (stochastic) to choose.
4. **"Scope management"** (Patronus AI) — Fewer tools = fewer wrong choices.
5. **"Encode proactiveness in tool descriptions"** (OpenAI) — Tool descriptions should say
   when NOT to use them, not just when to use them.
