Eigma

View saved version →

---
name: eigma-research
description: "Use when the user asks for research on a whole subject area, or wants to work through a whole field systematically, rather than for something in the current chat: a survey, a literature review, a state of the field, a systematic study of a domain, a structured way through an area the user wants to master, or getting the full picture of a topic before building on it (in any language, e.g. \"系统调研一下 X\", \"我想系统性地学习 X 领域\", \"do a literature review on Y\", \"I want to work through Z systematically\", \"give me the state of the field\"). It surveys the area, agrees an outline with the user, researches each item, and writes the result into their Eigma wiki as one index page plus one page per concept."
---

# Researching a subject area into Eigma

Eigma is the user's personal wiki. This skill turns a broad research request into a set of wiki pages: one index page that maps the area, plus one page per concept, all linked together and each carrying quizzes so the user can actually retain it.

Where the understanding comes from: the page itself. Explain the concept rather than naming it: what it is, how it works, what the evidence behind it is, and what it trades off. A page that only makes sense to someone who already understands the concept has not explained it. Making the concept stick is the quizzes' job, not the prose's, so the page's own job is to make it understandable in the first place, never to serve as a pointer back to an understanding formed somewhere else.

Work in three phases and stop between phase 1 and phase 2. Phase 1 is cheap and takes seconds; phase 2 spends real time and search budget. Agreeing the outline first is what keeps that spend on target.

## Phase 1: Scope (no web search)

1. Find out what the user already has, and decide where this survey belongs in it rather than beside it. Call `eigma_browse_wiki` once for the chapter and title tree. That is the only browse this survey makes and you now have the tree in context; checking the individual items against the wiki is a separate single call in step 3, once you have items to check. Read that tree before you draft anything, and settle THIS SURVEY'S CHAPTER, the one place all of its pages will live. It is always a top-level chapter, because the groups below need the level under it. If the tree already has a chapter that IS this area, that one is the survey's chapter and you reuse its exact spelling, so the user ends up with one place for this field instead of two. If the area is only a part of some broader chapter the user has, do not file the survey inside that chapter: nesting it there would spend the level the groups need and the survey would arrive flat. Give the area its own chapter next to it instead, and say so in the outline. Reuse a chapter only when a user opening it would expect to find these pages in it; a chapter that is merely next door is not this survey's chapter, because a page filed under one it does not belong to has no real neighbours and the user will not look for it there. When nothing in the tree is about this area, the survey gets its own new chapter, and for a field the user has not covered before that is the ordinary case. If a concept you would cover already has a page in the wiki, never make a second page for it here: mark that item UPDATE where this research adds something the existing page does not have, leave it out where it does not, and either way the page stays in the chapter it already lives in and is reached from the index by its link like every other item. Two half pages about one concept is worse than either of them, because the review schedule then tracks them separately and the user meets the concept twice and learns it neither time. For an item you mark UPDATE you will call `eigma_read_page` on that page before writing it and send back the COMPLETE integrated page: saving REPLACES that page's body, so every sentence of it you do not carry over is deleted from the user's wiki, and an update body written from your research alone destroys what was there.
2. From your own knowledge, draft two lists:
   - ITEMS: the objects to research, one page each. A page is the unit the user gets scheduled to review and quizzed on by itself, so an item earns its own page when it has to be recallable on its own, has its own sources behind it, and makes its own tradeoffs. Variants, stages, or refinements of a single idea go together on one page instead of being split into thin ones nobody would be quizzed on separately. What this survey is for decides which items exist at all: the user wants a working mental model of this field from a survey they can finish in one sitting, and they may never come back for more, so everything they need in order to make sense of the field earns a page of its own here. What is real but marginal is named in a sentence on the page it sits closest to, rather than given a thin page nobody would be quizzed on separately. Settle this while you still have the list in front of you, because once the user has agreed the outline the items are theirs, not yours to quietly drop. A survey of this shape runs to around twenty pages: well past that, concepts are being split into pages too thin to be worth reviewing separately, and well short of it, an area the reader needs is missing entirely. Two things that are only understood against each other belong on one page with both of them on it, rather than split apart onto pages that each spend their opening explaining the other: an assumption and its opposite, a notation and the query language written over it, a method and its variants. Before you settle the list, look for any item whose page would mostly be about a different item, and merge it into that one. Split the items into groups, and show them grouped in the outline: a group is a set of items the user would think about in the same breath. The groups you settle on are also how the wiki files these pages, so a group's name can become the second level of its pages' chapter; that changes nothing about how you choose the groups. A group is also the unit you write and send in below: everything you draft inside one message shares the same room, so a group written in a message of its own gets that message's room to itself. A group has to be worth the message it gets, and it can miss that in either direction: cram the whole area into one or two groups and the pages you draft last come out thin, but slice it so fine that a group is down to a page or two and the message is barely used, which costs the same pages the same depth. If a group would go out nearly empty, its items belonged with the group next to it; if a group covers most of the area, it was never a division of anything. An item that genuinely earns a page also arrives with enough material to divide into real sections, which is what the page-writing guidance below asks of it.
   - FIELDS: the dimensions every concept page must COVER, so the pages are comparable. They are a coverage requirement, not a section template: each page lays its own material out its own way, and a field counts as covered wherever on the page it is actually treated. Agree on FOUR, or FIVE at the very most, and never more than five. Choose them for THIS area rather than reaching for a generic set; if you need somewhere to start, what it is, how it works, and where it breaks down will serve for three of them, and the remaining one has to come from this area itself: the dimension along which people in it actually disagree, or the thing practitioners get wrong about it. An area with its own natural dimensions should use those for all four. Do not add a sixth. A dimension that is answered by naming things is a bad dimension: if the honest treatment of a field would be a list of systems, tools, papers or authors, that field is not teaching anything, and the page would be better for a dimension that cannot be answered without saying how something behaves. The material gathered for a concept is divided among its fields, so a field is not free: each one you add takes space away from every other one, and doubling the number of fields roughly halves what each of them gets. Fewer fields is how the treatment of each one gets deep enough to explain something instead of announcing it.
3. Check that item list against the wiki in ONE `eigma_resolve_pages` call before you show it to anyone, carrying every item at once, each as {title, summary, aka}. `aka` is the same concept's name in the wiki's language, and where the survey and the wiki are in different languages it is not optional: the match is on wording alone, so a Chinese item never reaches its English page without it, and the page it fails to reach is the page this survey then forks. An item whose candidate comes back marked SAME TITLE is that page: it is an UPDATE and it keeps that page's title and `category_path` exactly. A candidate not marked SAME TITLE is a near name and not a verdict, so mark UPDATE only where it is genuinely the same concept. An item that comes back with no candidate is NEW. Do this once, with every item together, and do not go back to browsing or searching to do the same job by eye: the wiki matches a draft to a page the way this call does, so a page this call did not find is a page your save will not find either.
4. Show the user the outline as a short table. Mark every item NEW, or UPDATE plus the exact title of the existing page it will rewrite. This tells the user up front what will be created and what will be changed.
5. Ask four things: which items to add or drop, whether these four or five fields are the right ones to swap around (not whether to add more, the cap is five), what time range the sources should cover, and how far the quizzes on each page should go: enough to check that the main idea landed, or enough to drill every claim the page makes. Put no number in that question; the user's answer decides it.
6. END your turn and wait. Do not search, draft pages, or call a write tool before the user answers.

Example of the table to show:

```
Area: <topic>
Chapter: <an existing chapter reused, spelled exactly as the tree spells it, or NEW>
Fields (4, max 5): <the four dimensions you chose for THIS area>

  group: <group name>
    item            status                  note
    Transformer     UPDATE "Transformer"    existing page, will be rewritten with the new material
    Mamba           NEW

  group: <another group>
    item            status                  note
    RWKV            NEW

Before I start, four things:
  1. Add or drop any items?
  2. Are these the right fields, or should one be swapped for another? (Four fields, five at the most.)
  3. What time range should the sources cover?
  4. How far should the quizzes on each page go: enough to check that the main idea landed, or enough to drill every claim the page makes?
```

## Phase 2: Research (after the user answers)

Take the agreed items and fields and research each item with the host's web search, filling every field. Weigh each source on whether its method is stated and checkable, whether the evidence behind it is sufficient, whether it was peer reviewed, whether the result has been reproduced, how recent it is, and how widely it is cited. Prefer primary sources over summaries of them.

Record the URL and title of every source as you go: phase 3 needs them for the citations.

Never invent a source, an author, or a date. When you cannot confirm something, keep the claim and mark it as unconfirmed next to the text, so the user can judge it in the same review where they accept or reject the page.

Do not stop to ask the user anything during this phase, and do not repeat a search you have already run.

## Phase 3: Write the pages and save

Produce one index page plus one page per agreed item.

The INDEX page: it is titled after the area itself and is filed at the survey's chapter, never below it, so it is the page the user meets first when they open this part of their wiki. This one page is the exception to the title rules further down, which govern the concept pages: an index may carry the area's own name even when that name matches its chapter, because it is the page the user opens to see the area whole. Its body is the CROSS-item view and only that: how the items relate to each other, where they cluster, what the area as a whole is arguing about, and where this area meets what the user already has. The overlap with the user's wiki is a sentence or two naming the pages already in their wiki that this area touches and saying how it touches them, whether it extends them, competes with them, or is what they were assuming; phase 1 already read the tree and resolved every item against it, so you know this without looking again. It is what lets the user attach a new field to what they already understand instead of storing it alongside, and it belongs in the body where they read it, not only in `links` where they do not. It must contain a table with one row per item and one column per agreed field, which every concept page covers however it chose to lay itself out, because that table is the only place in the entire survey where the items stand side by side; without it the user has pages about the parts and nothing about the shape of the whole. Anything that is true of a single item belongs on that item's own page, not here. Its `links` array must be COMPLETE: the exact title of every concept page in this survey, from every group of the outline and not only the group it is saved with, none missing, and each spelled as the receipt for that page spelled it, so the index reaches all of them in the knowledge graph.

Each CONCEPT page: a real lead paragraph (2-4 sentences), then sections that follow THIS concept's own material. The agreed fields are what the page must COVER, not a template for how to lay it out: there is no heading per field, no required order, and a field can be covered inside a section about something else or run across two of them. Give the page the divisions its own material actually has, in its own order, however many that turns out to be. Covering a field is not appending a section for it: a field is covered wherever this page's own argument reaches it, which on one concept comes early and on another comes late. Walking the agreed fields in their listed order, so that every page closes on whichever field the list happens to end with, is that template returning through the tail of the page; let each page end where its own argument ends. Pages in the same survey are EXPECTED to look different from each other, because the concepts differ; a set of pages whose headings all match is a template that was filled in, not a set of pages that were written. A heading exists only because there is something substantial under it: if a division would hold a single sentence, it is not a section, so fold it into the one next to it instead of giving it a heading of its own. Never a one-liner and never an undifferentiated blob. A concept page is self-sufficient for its own concept: what the sources disagree about on THIS concept, the tradeoffs THIS concept makes, and the evidence behind the claims about it all belong here, and a reader who never opens the index page must still get all of it. That is depth about one item, not a copy of the index: the cross-item comparison of the whole set stays on the index page. On a research page, the material IS the outline agreed in phase 1 and the sources gathered in phase 2, so drawing on them is depth, not padding. Write from those sources; where you fall back on your own knowledge, mark that claim unconfirmed. Wherever the page treats one of the agreed fields it must state the actual content: how the mechanism works, what the evidence is, what the specific claims are, and any disagreement between the sources. Each page also carries one concrete case of its own: a particular model, a particular query, a particular pair of things that get mistaken for each other. Introduce it where the mechanism is explained, run the mechanism on it right there, and bring the same case back later where the page reaches this concept's limits, so the reader follows one particular through the page and watches it behave differently as the argument moves. A case named once and never used again has not been worked. Where the page says something goes wrong without this concept, show it going wrong on that same case and say what the wrong outcome actually is, instead of reporting that a problem exists. Text that only restates the field's name back, or gestures at the topic in one sentence, has not covered that field. Neither has a list of names. Naming the systems, tools, papers or people associated with a field is not treating it: if the reader cannot tell from what you wrote how any two of those differ or why one would be chosen over another, the names are decoration and the space they took belonged to the explanation. Either say what distinguishes one of them and drop the rest, or leave the names out and spend the room on the mechanism. A source you are citing is not a name list: the work, author or year behind a specific claim always stays, with its footnote. Nor is a deliberate omission: a concept this survey chose not to give a page to may be named on the page it sits closest to, in a sentence saying what it is and why it falls outside this survey, and it goes on that neighbouring page rather than the index whenever it has one. One name carrying a clause of substance is a mention; three names in a row is the list this rule just forbade. A mention is not a link either, so a concept with no page in this survey never goes into any `links` array. Concrete figures belong here: where a gathered source supports it and a claim rests on it, a benchmark score, a publication year, a parameter count, or a throughput comparison goes into the page together with its citation. Those are the evidence a survey is made of, not the incidental look-it-up trivia a filing rule tells you to drop from an ordinary chat. Every agreed field must be covered somewhere on the page. If the gathered sources give you genuinely nothing about one of them for this particular concept, then that field goes uncovered and you write nothing rather than filler, but that is the rare exception and never the shape of the page: the fields were chosen because they fit these concepts, so expect to cover nearly all of them on nearly every page. Free structure is freedom over the page's headings, never permission to leave a field uncovered. Every page does the whole job for its own concept: the case, the mechanism running on it, the evidence behind the claims. Before you save a page, check it against what it was meant to do rather than against its length: has this page run its own case, shown the mechanism working on that case, and given the evidence behind its claims? A page that says what something is and lists what it trades off, and stops there, has done none of the three and is not finished however long it runs. Let each page end where its own material ends, since one concept genuinely takes more room than another; and padding, repeating in other words what the page already said, or adding sections that restate their own headings fails this check just as badly as stopping early.

One node = one concept, titled by its ENTITY name: a SHORT noun phrase, like a wiki page title. Aim for 1-3 words, rarely more than 4; never a sentence, a description, or a qualifier-laden phrase (write "Reward model", not "The reward model used in RLHF training"). The title must NOT repeat, equal, or be the singular/plural of its category; an overview or umbrella page uses a concrete entity name, not the category name (under "Supabase", a page is "Edge Functions", not "Supabase Edge Functions"; under "LLM Agents", the overview is "Agent loop", not "LLM Agent"). A survey tempts thematic section titles; resist that here too: each concept page is titled by the entity it is about, and a thematic slice of the survey belongs as a section inside a concept page or on the index page, never as a page of its own.

category_path is the CHAPTER the page lives under, NEVER the page's own title, and normally ONE level (the page itself is the second level; use two levels only for an unusually fine-grained concept). Reuse an existing chapter whenever the page GENUINELY belongs in it, rather than inventing a near-duplicate of a chapter that already exists — but when the concept belongs to NONE of the existing chapters, create the chapter it does belong to. Never force a page into an unrelated chapter just to avoid making a new one: a page with no real neighbours has nothing to link to and the user will not find it there.

The category rule just above calls one level normal and a second level an exception for an unusually fine-grained concept; on this survey the second level is the norm, not the exception. Every page this survey saves, the index page included, is filed under THE SURVEY'S CHAPTER, the one you settled in phase 1, and under nothing else. Each concept page is filed under that chapter and then under the group it was listed in; the index page is filed under that chapter alone. Never a chapter outside the survey's chapter for any page in this survey, with one exception: an item you marked UPDATE in phase 1 already has a page, and that page stays in the chapter it already lives in, because moving someone's existing page is not this survey's job; the index reaches it by its link like every other item. And never a level below the group: if a group looks like it needs sub-groups, its pages stay where they are and their titles carry the finer distinction.

Citations: ONLY if the conversation actually used OUTSIDE sources — links/URLs shared in the chat, uploaded files or PDFs, or web-search / browsing results — add a "[^N]" footnote marker (caret syntax, not "[1]") after each sentence a source supports, and end that page's "body_md" with ONE "## References" section of "[^N]: [label](url)" lines, numbered per page from 1 (reuse the same "[^N]" when one source supports several sentences). Use only the title/URL the conversation gives; never invent an author or date. If the chat was just your own answer with NO outside sources, add NO "[^N]" and NO "## References" section (never a placeholder).

Math: write as LaTeX — inline in "$...$", a displayed equation on its own line in "$$...$$" (never plain text or Unicode symbols, never \( \) or \[ \]); escape each backslash so the JSON stays valid.

summary: ONE short line (<= 25 words) giving the page's gist, distinct from the lead's first sentence.

Write the summary in the same language as the body of the page it belongs to, always: it is the first thing the user sees in the list and the card, so a Chinese page with an English summary is wrong even though both halves are correct on their own. The language you are writing the page in is the language the summary is in.

links: CONNECT THE GRAPH — give each page a "links" array of related concept titles, including BOTH the other new pages it relates to AND the EXACT titles of relevant EXISTING pages from the outline, so the page joins the user's knowledge graph instead of sitting isolated.

Diagrams: for a structure, flow, hierarchy, or relationship, "body_md" MAY include a ```mermaid or ```svg fenced diagram, which Eigma renders. Use it only where it makes the page clearer than prose; most pages need none.

Interactive: when a concept is genuinely dynamic (a process, an oscillation, a tradeoff curve), "body_md" MAY include ONE ```animation fenced block, a small self-contained interactive explainer Eigma runs in a sandbox. It MUST be self-contained: all CSS/JS inline, NO external network (no external URLs, CDN scripts, web fonts, or fetch), images only as data: URIs, under 60KB. Drive it with a <canvas> and requestAnimationFrame and draw a clear first frame. Most pages need none.

Eigma also renders GFM tables and syntax-highlighted fenced code blocks. A defining algorithm, equation-in-code, or API shape belongs in a fenced code block with its language tag; most concept pages need none. A table is a normal way to lay out a section whose material is parallel, such as several variants of this one concept set side by side, with one column per property they differ on, so the table says how they differ rather than merely which ones exist. A table whose cells are only names is the name list this page was told not to write, moved into a grid. Use one on a concept page wherever the material is shaped that way.

quizzes: 1-3 per page (REQUIRED), each a selection-only question that needs UNDERSTANDING of the concept to answer: why it works, how it behaves, what happens if, or which case it applies to. Each is an object {kind, prompt, options, answer, explanation?}. kind is "mcq" (4 options, one correct), "cloze" (a sentence with "____" + 4 options), or "truefalse" (answer true/false). For mcq/cloze the "answer" must be one of the "options" VERBATIM (the option text, not a letter/index); distractors are plausible near-misses, not obvious non-answers, no option may run more than half again as long as the shortest, reached by making each wrong option a MORE substantial claim, never by shortening the right one, and no stem asks which statement is "best" or "most accurate". When adding to a page that already exists, quiz only the new material and do not repeat a quiz the page already has.

How far the quizzes go on each page is whatever the user answered when you agreed the outline, and that answer governs. If they asked you to drill every claim, then each claim the page makes gets its own question, however many that comes to on this particular page, and any smaller count stated anywhere else does not apply to this survey. If they asked only that the main idea landed, or said nothing about it, leave the count where the rules above put it.

`explanation` is written as optional in the field list above and in the rules you were given; on this survey it is not optional. Every quiz carries one, saying why the answer is right and, where a wrong option is tempting, why that one is wrong. This is a review product: the explanation is what the user reads at the moment they got the question wrong, so a quiz sent without one teaches nothing exactly when it matters most, and a quiz whose explanation only restates the answer is the same failure in a longer form.

The field list above and the rules you were given both offer `truefalse` as one of the kinds, and those rules also ask you to vary the form and to mix in false statements; on this survey none of that applies. Write every quiz as `mcq` or `cloze`, each with four options, and do not send a `truefalse` item at all. A two-way question is answerable at even odds by a reader who knows nothing, and the ways of pushing it above even odds all leak the answer through wording rather than through the claim, so on a page whose purpose is to be understood it is the one format that cannot do the job. An `mcq` whose options are the two sides of a yes-or-no is the same question wearing a different label, and it fails this for the same reason.

The wrong options are where a question is won or lost. Every one of them has to be a position someone working in this area could actually hold, so take them from the neighbouring concepts in this same survey, from whatever this concept is most often confused with, or from the answer that was right before this concept existed. An option drawn from an unrelated subject, or one that is absurd on its face, teaches nothing: the reader picks the survivor without ever considering the claim, and a page they never opened scores the same as one they studied. All four options have to come out about the same length, none more than half again as long as the shortest, because a reader who has noticed that the fullest-sounding option is the right one scores without reading the claim at all, and one who notices the reverse scores just as well. Get there by making each wrong option a more substantial claim, never by padding it out or by cutting the right one short: a padded option and an absurd one are the same failure as an off-domain one, and the length of an option should tell the reader nothing. Each question tests what the page actually claims, not how the page happens to word it: if the correct option repeats the wording of a sentence on the page, a reader who matched the words scored without thinking, so write that one again.

Those quizzes must travel with their page in the save call below, not a later edit: `eigma_suggest_edits` cannot reach a page that is still awaiting review in the inbox. On an UPDATE page, this pass covers only the material THIS research added, not the material already in the existing page.

Then save, and do not write the whole survey in one go. Work through the outline one group at a time: write the pages of a single group fully, call `eigma_save_notes` with exactly those pages, and only once the receipt comes back start writing the next group. Everything you draft inside one message shares the same room, so the pages you draft last are the ones that come out thin; a group written in a message of its own gets that message's room to itself. Writing a group at a time must not turn the survey into separate surveys. Each group after the first is written as the continuation of the ones already saved: keep using the terms you defined there rather than defining them again, carry the same worked case forward where it still applies, and where a page needs something an earlier page already explains, link to that page by its exact title instead of explaining it a second time. Before you start a group, say to yourself in one line what the groups before it established, and write the new pages so a reader arriving from them is not told the same thing twice or left to guess what changed. Each call comes back with a receipt naming the pages it saved, and if a receipt reports pages that did not fit, call `eigma_save_notes` again with exactly those remaining pages before moving on. Do not try to work out how much fits in one payload; that is decided for you. A receipt is not a stopping point: do not end your turn, and do not report progress to the user, between one group and the next. Go straight from a receipt into writing the next group, and keep going until every group in the outline has been saved. The index page goes with the LAST group, in that same call, and is written after all the other pages exist: it is the only page whose subject is the other pages, so it is written from the pages you actually wrote rather than from the outline you planned, and its `links` name every page this survey saved, each spelled exactly as the receipts spelled it. When that last call's receipt has come back, show the user what the receipts reported and END your turn. The pages go to the user's Eigma review inbox, where the user accepts or rejects each one, so nothing you send changes the wiki on its own.

For an item marked UPDATE, call `eigma_read_page` on that page first and put the COMPLETE integrated page in `body_md`, because saving replaces that page's body. Reuse its exact title. When several UPDATE items live in the same chapter, read them in one call: `eigma_read_page` with that `category_path` and no `title` returns every page in that chapter at once.

## What not to do

- Do not skip phase 1 or start searching before the user has answered.
- Do not put the whole survey on one page. One concept per page is what makes the quizzes and the review schedule work.
- Do not invent sources, authors, or dates. Mark what you could not confirm instead.
- Do not run the same search twice, and do not call a read tool again with arguments you already used.
- Do not manufacture changes to an area the user has already organized well. If the existing pages already cover an item properly, say so and leave it out.
- Do not claim you saved anything unless `eigma_save_notes` came back with a receipt naming the pages.

Write everything in the same language the user is using, and that means every field the user reads, not just the body: the summary, the quiz prompts, the options, and the explanations. A page whose body is in one language and whose summary is in another is wrong even though each is correct on its own. Titles and `category_path` are the exception and stay as the entity and chapter names the rules above give them, because they are what pages are matched and linked by, not prose the user reads.