Learn

---
name: learn
description: >
  Researches a topic from the web and adds it to the project's lode/ documentation.
  Use /learn <topic> to research official docs and persist findings. Supports --skill flag
  to output as a SKILL.md instead.
  Triggers on: learn about, research topic, add to lode from web, learn this, deep research.
argument-hint: "<topic> [--skill [--global]]"
allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Agent
---

# Learn Skill

Orchestrates research via the `sme-researcher` agent and persists findings.

**Arguments:** `$ARGUMENTS`

## Bounds

- **Research time**: ~2-3 minutes maximum
- **Sources**: Stop after 6 quality sources found
- **Tell sme-researcher in the prompt** to stop after 5 tool turns
- If sources found quickly, stop early, do not hunt for more

## Steps

### 1. Parse arguments

- Extract `<topic>` and optional flags (`--skill`, `--global`) from arguments.
- Normalize topic to **kebab-case** for file naming.
- If topic is empty, show usage examples and stop.

**Extended invocation: suggest improvements to an existing skill.**
The format `/learn <topic> and suggest improvements to the '<skill-name>' skill` is fully
supported. After writing the lode draft, read the named SKILL.md and present a diff-style
list of improvements drawn from the research findings. Ask "Apply these improvements?" before
making any changes. This pattern works for lode output only (not `--skill`).

### 2. Determine output target

Check if `lode/` exists (`Glob: lode/lode-map.md`):

| Condition | Output target |
|-----------|--------------|
| `lode/` exists, no `--skill` flag | **lode/** (default) |
| `--skill` flag provided | **SKILL.md** (project-local or `--global`) |
| No `lode/` and no `--skill` flag | **Prompt user**: create lode/, create as skill, or create as global skill |

**If lode/ exists:** Read `lode/lode-map.md` to identify any existing lode files related to the topic. Skim relevant ones so the researcher can focus on gaps, not already-documented ground.

### 3. Research via sme-researcher

**Bounds:**
- Stop after 6 quality sources (~2-3 minutes max)
- Tell sme-researcher in the prompt to stop after 5 tool turns
- If sources found quickly, stop early

Spawn the `sme-researcher` agent with this prompt. Limit it to 5 tool turns in the prompt text:

> Research `<topic>` for use in this project. Focus on official documentation. {output-specific instructions, see below}
>
> If any related lode files exist, note them and focus on gaps not yet covered.

**For lode output:** Instruct sme-researcher to return synthesized findings without writing files. Include: "Do NOT write files. Return your synthesized findings with source URLs and scrape dates so I can draft them into lode/tmp/."

**For skill output:** Instruct sme-researcher to return findings without persisting. Include: "Do NOT write files. Return your synthesized findings with source URLs and scrape dates so I can format them as a SKILL.md."

**Empty response handling:** The sme-researcher agent frequently completes its
research but returns an empty body on the first call (only agentId + usage metadata visible).
This is normal behaviour. If the Agent result contains no findings text:
1. Automatically resume the agent with `SendMessage` to its returned `agentId`
2. Prompt: "Please provide your complete synthesized findings on `<topic>`. Include all source URLs and key recommendations you researched."
3. Do NOT ask the user: handle the resume transparently.

### 4. Write draft (lode path) or skill output (--skill path)

**For lode output:** Write findings to `lode/tmp/<topic-kebab-case>.md` as a draft. Follow lode file conventions (timestamp, relative links). Then show the user a summary of the draft and ask:

**250-line enforcement:** Before writing, estimate content volume. If a single file would
exceed 250 lines, split at a natural topic boundary into two focused sub-files, write both
to `lode/tmp/` and promote both together. Never write a lode file over 250 lines.

**Mermaid diagrams:** Include Mermaid diagrams only where they add genuine architectural
clarity (e.g., data flows, state machines, pipeline stages). Do NOT add Mermaid to
config/reference docs where tables and code blocks are clearer.

> Draft saved to `lode/tmp/<topic>.md`. Promote to permanent lode?

On user approval:
1. Move the file from `lode/tmp/` to the appropriate location based on topic domain:
   - .NET patterns/tools -> `lode/dotnet/<topic>.md`
   - Infrastructure/tooling -> `lode/infrastructure/<topic>.md`
   - Cross-cutting concerns -> `lode/<topic>.md` (root level)
2. Update `lode/lode-map.md` to include the new entry in both Quick Reference and Directory Structure
3. Delete the tmp draft

Never create `lode/research/`: research findings are integrated into domain-specific directories.

If the user declines, leave the draft in `lode/tmp/` for later review. Note: `lode/tmp/` is git-ignored, so drafts will not be committed.

**For skill output:** Write findings directly to skill location:

**Location:**
- Default: `.claude/skills/<topic-kebab-case>/SKILL.md`
- With `--global`: `~/.claude/skills/<topic-kebab-case>/SKILL.md`

If a file already exists at that path, warn the user before overwriting.

**SKILL.md format:** Load `${CLAUDE_SKILL_DIR}/assets/skill-template.md` for the output structure. Adapt sections to fit, omit empty ones, add others if warranted. Rules:
- `name`: max 64 chars, lowercase + numbers + hyphens only
- Body: under 500 lines, imperative language, version-specific
- **Never fabricate APIs or features not found in sources**

### 5. Confirm

```
Learned: <topic>
Sources: <count> URLs scraped
Saved to: <path>   (or: Draft in lode/tmp/<topic>.md — awaiting promotion)
```

## Self-Improvement

After completing any research session:

1. **Record failed or blocked topics**: If a research topic returned no useful sources (paywalled, undocumented, too new), add a Troubleshooting note with the date and reason so future sessions do not repeat the search.
2. **Note already-covered topics**: If the user asked to research a topic already fully in lode/, add a Troubleshooting note (topic name + lode path) so future sessions surface the existing doc immediately.
3. **Update sme-researcher retry guidance**: If the empty-result resume pattern required more than one retry, or a different prompt formulation worked better, update the Troubleshooting section.
4. **Log source quality patterns**: If a particular site consistently provides high or low quality content for this domain, note it in Troubleshooting so sme-researcher can be guided accordingly.

## Troubleshooting

- **sme-researcher returns empty result**: this is normal. Resume with the returned agentId and prompt: "Please provide your complete synthesized findings on [topic]". Do not ask the user
- **Topic maps to an existing lode file**, read the existing file first to identify gaps. The researcher should focus on what is not yet documented, not re-document existing content
- **Draft file would exceed 250 lines**, split at a natural topic boundary into two focused sub-files and write both to `lode/tmp/`. Never write a lode file over 250 lines
- **No lode/ directory found and no --skill flag**, prompt the user for their preferred output: create lode/, create as skill, or create as global skill
- **--global flag used without --skill**: global output only applies to skill files. Prompt for clarification or treat as `--skill --global`