learn

## EXECUTE NOW

**Topic: $ARGUMENTS**

Parse immediately:
- If topic provided: research that topic
- If topic empty: read `self/goals.md` for highest-priority unexplored direction and propose it
- If topic includes `--deep`/`--light`/`--moderate`: force that depth, strip flag from topic
- If no topic and no goals.md: ask "What would you like to research?"

**Steps:**

1. **Read config** — tool preferences, depth, domain vocabulary
2. **Determine depth** — from flags, config default, or fallback to moderate
3. **Research** — tool cascade: primary → fallback → last resort
4. **File to inbox** — with full provenance metadata
5. **Chain to processing** — next step based on pipeline chaining mode
6. **Update goals.md** — append new research directions discovered

**START NOW.** Reference below explains methodology.

---

## Step 1: Read Configuration

```
ops/config.yaml             — research tools, depth, pipeline chaining
ops/derivation-manifest.md  — domain vocabulary (inbox folder, reduce skill name)
```

**From config.yaml** (defaults if missing):
```yaml
research:
  primary: exa-deep-research      # exa-deep-research | exa-web-search | web-search
  fallback: exa-web-search
  last_resort: web-search
  default_depth: moderate          # light | moderate | deep
pipeline:
  chaining: suggested             # manual | suggested | automatic
```

**From derivation-manifest.md** (universal defaults if missing):
- Inbox folder: `inbox/` (could be `journal/`, `encounters/`, etc.)
- Reduce skill name: `/reduce` (could be `/surface`, `/break-down`, etc.)
- Domain name and hub MOC name

---

## Step 2: Determine Depth

Priority: explicit flag > config default > `moderate`

| Depth | Tool | Sources | Duration | Use When |
|-------|------|---------|----------|----------|
| light | WebSearch | 2-3 | ~5s | Checking a specific fact |
| moderate | mcp__exa__web_search_exa | 5-8 | ~10-30s | Exploring a subtopic |
| deep | mcp__exa__deep_researcher_start | Comprehensive | 15s-3min | Major research direction |

---

## Step 3: Research — Tool Cascade

Output header:
```
Researching: [topic]

  Depth: [depth]
  Using: [tool name]
```

Try tools in config priority order. If a tool fails (MCP unavailable, error, empty results), fall to next tier. If ALL tiers fail:
```
FAIL: Research failed — no research tools available

  Tried:
    1. [primary] — [error]
    2. [fallback] — [error]
    3. WebSearch — [error]

  Try again later or manually add research to [inbox-folder]/
```

### Tool Invocation Patterns

**exa-deep-research:**
```
mcp__exa__deep_researcher_start
  instructions: "Research comprehensively: [topic]. Focus on practical findings, key patterns, recent developments, and actionable insights."
  model: "exa-research-fast" (moderate) | "exa-research" (deep)
```
Poll with `mcp__exa__deep_researcher_check` until `completed`. Output during wait:
```
  Research ID: [id]
  Waiting for results...
```

**exa-web-search:**
```
mcp__exa__web_search_exa  query: "[topic]"  numResults: 8
```

**web-search (last resort, also used for light depth):**
```
WebSearch  query: "[topic]"
```

On completion: `Research complete — [source count] sources analyzed`

---

## Step 4: File Results to Inbox

**Filename:** `YYYY-MM-DD-[slugified-topic].md` — lowercase, spaces to hyphens, no special chars.

**Write to** the domain inbox folder (from derivation-manifest, default `inbox/`). Create folder if missing.

### Provenance Frontmatter

Every field serves the provenance chain. The `exa_prompt` field is most critical — it captures the intellectual context that shaped the research.

```yaml
---
description: [1-2 sentence summary of key findings]
source_type: exa-deep-research | exa-web-search | web-search
exa_prompt: "[full query/instruction string sent to the research tool]"
exa_research_id: "[deep researcher ID, omit for web search]"
exa_model: "[exa-research-fast | exa-research, omit for web search]"
exa_tool: "[mcp tool name, omit for deep researcher]"
generated: [ISO 8601 timestamp — run: date -u +"%Y-%m-%dT%H:%M:%SZ"]
domain: "[domain name from derivation-manifest]"
topics: ["[[domain-hub-moc]]"]
---
```

Include only the fields relevant to the tool used:
- Deep researcher: `source_type`, `exa_prompt`, `exa_research_id`, `exa_model`, `generated`, `domain`, `topics`
- Exa web search: `source_type`, `exa_prompt`, `exa_tool`, `generated`, `domain`, `topics`
- WebSearch: `source_type`, `exa_prompt`, `exa_tool`, `generated`, `domain`, `topics`

### Body Structure

Format for downstream reduce extraction — findings as clear propositions, not raw dumps:

```markdown
# [Topic Title]

## Key Findings

[Synthesized findings organized by theme, not by source. Each finding
should be a clear proposition the reduce phase can extract as an atomic insight.]

## Sources

[List of sources with titles and URLs]

## Research Directions

[New questions, unexplored angles, follow-up topics. These feed goals.md.]
```

---

## Step 5: Chain to Processing

Read chaining mode from config (default: `suggested`).

```
Research complete

  Filed to: [inbox-folder]/[filename]

  Next: /[reduce-skill-name] [inbox-folder]/[filename]
```

Append based on mode:
- **manual:** (nothing extra)
- **suggested:** `Ready for processing when you are.`
- **automatic:** Replace "Next" line with `Queued for /[reduce-skill-name] -- processing will begin automatically.`

---

## Step 6: Update goals.md

If `self/goals.md` exists AND the research uncovered meaningful new directions:

1. Read goals.md, match existing format
2. Append under the appropriate section:
   ```
   - [New direction] (discovered via /learn: [original topic])
   ```

Skip silently if goals.md missing or no meaningful directions found. Do not add filler.

---

## Output Summary

Clean output wrapping the full flow:
```
ars contexta

Researching: [topic]

  Depth: [depth]
  Using: [tool name]
  [Research ID: abc-123]

  Research complete -- [N] sources analyzed

  Filed to: [inbox-folder]/[filename