/explain-research

Use when the user asks about something outside this codebase (a protocol, algorithm, tool, term, news) or about a concept the code relies on and you are not certain of the details. Load explain for how to teach it; this skill covers finding and distilling the facts.

1. Search with intent

1. Write down the question the user is really asking, in one line.
2. websearch with two or three different wordings (the name, the problem it solves, "how X works"). Add the year for anything that changes.
3. Prefer, in order: official docs and specs, the project's own repo or README, a university or well-known engineering blog, a reputable explainer. Avoid content farms and unsourced listicles.
4. webfetch the best two or three. Read them; do not summarise search snippets.
5. When sources disagree, or a page is old, say so. When you cannot find it, say that; do not fill the gap.

2. Distill

Turn what you read into a short, plain set of claims, not a copy of the article:

• One sentence: what it is, for someone smart who has never heard of it.
• One sentence: what problem it solves (the "why it exists").
• A concrete example with real values that you can carry through the whole explanation.
• The 3–6 steps of how it works, in order.
• One thing people get wrong, and the limit of the idea.
• Terms: for each piece of jargon you must keep, a five-word gloss at first use. Cut the rest.

Simplify by choosing, not by lying. Drop detail, keep every claim true. Use an analogy only when it maps step for step, and say where it stops fitting. Numbers, dates and versions come from a source you opened. Mark anything you inferred.

3. Pull an image only if it earns its place

A picture earns its place when the thing is physical or visual (hardware, a UI, a chart, a map, a famous diagram) and drawing it would be worse than showing it. Do not add images as decoration.

1. Find a direct image URL: in the page you fetched look for <img src>, og:image, or a Wikimedia Commons file URL. The URL must end in a real image (png, jpg, jpeg, gif, webp, svg) or return an image content type. A web page URL is not an image.
2. Prefer official docs, Wikimedia Commons and the project's own repo. Note the licence when the page states one; if it is unclear or restrictive, redraw the idea on the board instead.
3. Hand the URL to the board brief (the sub-agent has board_image with a URL source but no web tools). Include a caption: what it shows and where it came from (Source: <site>).
4. Under 6 MiB; png/jpeg/gif/webp/svg only. If it will not load, the sub-agent should redraw it with shapes rather than skip the idea.

Prefer a diagram you draw over a screenshot of someone else's diagram when the idea is simple. A drawn sketch can be pointed at and edited.

4. Icons (Lucide)

For generic things (a user, a server, a database, a cloud, a lock, a key, a file, a clock, a bug, a globe, a git branch, a package, a message) use a Lucide icon instead of searching for a picture. They are consistent, free and quiet.

• Name them in the brief by their kebab-case name: database, server, cloud, user, users, lock, key-round, file-text, clock, bug, globe, git-branch, package, message-square, shield-check, cpu, hard-drive, network, workflow. Browse names at lucide.dev/icons.
• The sub-agent places each with board_image and source: { icon: "<name>" }, width 48–96, and a text label beside or below it.
• One icon per kind of thing, used the same way every time. An icon never replaces the label.
• Brand logos are not Lucide icons; use the product's own logo from its site if a logo is needed, or just the name in a rectangle.

5. Teach it

Follow explain: hook question, the concrete example, the steps, the name last, a second case. Then route the answer:

• A short factual answer → chat, with the two or three claims and sources.
• A mechanism or comparison the user will want to see → the board sub-agent with a storyboard brief that carries your researched facts, the real example values, any image URLs with captions, the icon names, and the sources to print in a small note.

Brief rules: the sub-agent cannot browse, so the brief must contain everything it draws, as final text. Put each source as Title — domain on a quiet note at the edge of the board.

6. Reply

Chat: two or three lines of the answer in plain words, then the sources as links. Say what you are unsure of.

Checks

• Every fact traces to a page you opened.
• A reader could repeat the explanation to a friend.
• Jargon is glossed once, at first use.
• Images have a direct URL, a caption and a source; icons have a label.
• Nothing is drawn that you could not source.