learn

name	learn
description	Research a topic and grow your knowledge graph. Uses Exa deep researcher, web search, or basic search to investigate topics, files results with full provenance, and chains to processing pipeline. Triggers on "/learn", "/learn [topic]", "research this", "find out about".
user-invocable	true
allowed-tools	Read, Write, Edit, Grep, Glob, Bash, mcp__exa__web_search_exa, mcp__exa__deep_researcher_start, mcp__exa__deep_researcher_check, WebSearch
context	fork

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

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.

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

# [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]

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

  [goals.md updated with N new research directions]

---

Error Handling

Error	Behavior
No topic, no goals.md	Ask: "What would you like to research?"
Exa MCP unavailable	Fall through cascade to WebSearch
All tools fail	Report failures with FAIL status, suggest manual inbox filing
Deep researcher timeout (>5 min)	Report timeout, suggest --moderate
Empty results	Report "No results found", suggest refining topic
Config files missing	Use defaults silently
Inbox folder missing	Create it before writing

---

Skill Selection Routing

After /learn, the self-building loop continues:

Phase	Skill	Purpose
Extract insights	/[reduce-name]	Mine research for atomic propositions
Find connections	/[reflect-name]	Link new insights to existing graph
Update old notes	/[reweave-name]	Backward pass on touched notes
Quality check	/[verify-name]	Description quality, schema, links

/learn is the entry point. Each run feeds the graph, and the graph feeds the next direction through goals.md.