Oleafly Research Loop

Oleafly Research Loop

This is the router for a whole research project. It does two jobs. It fixes the file layout that every other Oleafly research skill reads and writes, so a sweep done in one session is still findable three weeks later. And it tells you which skill to load for the stage you are actually in, so you do not improvise a procedure that already exists.

Load this skill when the work spans more than one step. For a single question ("what is the DOI for this paper") answer it directly and skip the loop.

Step 1. Read the ground before planning

Do this once per session, in this order. It is cheap and it stops you from rebuilding state that already exists.

1. list_notes with {}. Earlier turns may have recorded the bibliography path, the venue, the citation style, or a naming convention. Notes beat guessing.
2. list_files with {}. Look for research/, figures/, review/, and any .bib file. This tells you whether the layout below already exists or has to be created.
3. project_map with {} when the tool is offered. It returns files, sections, labels, bibKeys, macros, inputGraph, unresolvedRefs and unresolvedCites. bibKeys and unresolvedCites are the two fields the research skills depend on. The tool is only available when the document engine advertises a document index, so if it is not in your tool list, fall back to step 4.
4. search_project with {"query": "\\addbibresource"} and then {"query": "\\bibliography{"} for LaTeX, or {"query": "bibliography"} for Typst and Markdown. The hit tells you which .bib file the project actually compiles against. Use that file. Do not create references.bib when another one is already wired in.

If list_files shows no research/ directory, create the layout in step 3 before doing any literature work.

Step 2. Plan the loop with update_todos

update_todos takes {"todos": [{"id": "...", "content": "...", "status": "pending"}]} and replaces the whole list every call, so always send the full list. Statuses are pending, in_progress, completed, cancelled. Keep exactly one item in_progress. The list is capped at 30 items and each content at 240 characters.

Write the plan in loop stages, not in tool calls. A good first plan for "help me write this paper" looks like this.

{"todos": [
  {"id": "sweep", "content": "Build the reading list for the research question", "status": "in_progress"},
  {"id": "related", "content": "Draft related work from the reading list", "status": "pending"},
  {"id": "claims", "content": "Audit the claims in the draft against their sources", "status": "pending"},
  {"id": "figures", "content": "Prepare the figures the argument needs", "status": "pending"},
  {"id": "review", "content": "Self review the full manuscript", "status": "pending"},
  {"id": "submit", "content": "Run the pre-submission checks for the target venue", "status": "pending"}
]}

Update the list when the shape of the work changes, not after every tool call.

Step 3. The project layout every research skill honours

Create what is missing with create_file and {"path": "research/notes", "is_dir": true}. The layout is the contract between skills, so do not rename parts of it to suit one session.

<key> is the citation key, formed as <firstauthor><year>-<slug>, all lowercase ASCII. First author surname, four digit year, then two or three words from the title joined by hyphens. vaswani2017-attention-transformer. Use the same key for the .bib entry, the source note, and the PDF, so the three always line up. If the project's existing .bib uses a different key scheme, follow the project. Consistency inside one bibliography matters more than this convention.

Record the deviation with remember_note when you follow a project scheme instead of this one.

Step 4. Load the skill for the stage you are in

Load one skill at a time with load_skill and {"id": "<skill id>"}. It returns the skill's absolute directory, its file tree, its frontmatter, and its instructions. Read a supporting file with read_skill_file and {"id": "<skill id>", "path": "references/handoffs.md"}.

Full trigger phrases are in references/handoffs.md. Read it when the user's request does not map cleanly onto a row above.

Step 5. Record durable conventions with remember_note

remember_note takes {"content": "..."} and the note survives into later sessions. Save a fact only when a future turn would get the work wrong without it.

Worth saving: the path of the bibliography the project compiles against, the citation key scheme when it differs from this skill's, the target venue and deadline, the citation style, a user preference about tone or terminology, and whether Python is available (step 6).

Not worth saving: anything already visible from project_map or list_files, the content of a paper, or a step you are about to do anyway. Notes are read on every turn, so noise there is expensive. Remove a stale one with forget_note and its id from list_notes.