LearnSAFE

Claude Code plugin that generates individualized knowledge systems from conversation. You describe how you think and work, have a conversation and get a complete second brain as markdown files you own.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

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

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.