agenticnotetaking/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]

  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.