Oleafly Related Work

A related-work section has one job: show where this work sits among what already exists, and why the gap it fills is a real gap. It is an argument, not an annotated bibliography. Paragraphs that open "Smith et al. proposed..." and close "...achieved good results" are a list with margins.

The hard rule of this skill: never write a citation key that is not already in the project bibliography. Not as a placeholder, not with a comment saying to fix it later, not because the paper obviously exists. An invented key either fails to compile or renders as a question mark that survives to submission. If you want to cite something that has no entry, stop and add the entry first (step 4).

Step 1. Establish the target

Answer these before writing a sentence. Ask when you cannot infer it.

• Which file. search_project with {"query": "Related Work"} or {"query": "\\section{Related"} finds an existing section. project_map with {} returns sections with file and line for each, and files for the project structure.
• Whether this is a new section, a rewrite, or a repair of an existing one. A rewrite of the user's prose needs their agreement first.
• The length budget. Related work is where page limits get lost. Ask for a paragraph count or a page fraction if the venue is tight.
• The markup. LaTeX, Typst and Markdown cite differently and the wrong syntax fails silently in two of the three. See references/citation-syntax.md.

Set the plan with update_todos.

Step 2. Inventory what you can cite

Three sources, in this order.

1. project_map with {}. Read bibKeys, which is the exact set of keys you are allowed to use, and unresolvedCites, which is the set of keys the document already cites with no entry behind them. A non empty unresolvedCites is a bug in the document and part of your job.
2. read_file with {"path": "research/reading-list.md"}. If a sweep ran, this is the thematic grouping already done, with a "why it matters" sentence per paper that is the seed of your prose. If the file does not exist, the sweep has not run: consider handing off to oleafly-literature-sweep before drafting, and say so.
3. project_library_search with {"query": "<topic>"} surfaces anything the user already wrote about this prior work elsewhere in the project, which you should not contradict.

When project_map is not offered, read_file the bibliography directly and take the keys from the @type{key, lines. search_project with {"query": "@"} locates them if you do not know the path.

Step 3. Group by theme, then order the themes

Group the papers by the question they answer, not by year and not by author. Three to five themes is the usual shape for a conference paper. Each theme becomes one paragraph, occasionally two.

Order the themes so that the last one is closest to this work. The section should narrow as it goes, ending where the contribution begins, so the transition into the next section needs no announcement.

Write the grouping down before you write prose. A three column sketch is enough: theme, the papers in it, the one sentence that paragraph must land.

Common groupings that work: by approach family (what they do), by the assumption they make (what they require), by the limitation they share (why the gap exists). The last one is the strongest when the paper's contribution is removing that limitation.

Step 4. Close the citation gaps before writing

Now, not later. For each paper you intend to cite that is not in bibKeys:

1. verify_citation with {"doi": "<doi>"}, or {"title": "<exact title>"} when there is no DOI.
2. A verified: false result means the paper is not confirmed. Do not cite it. Either drop the point or find a source that does verify.
3. Append the returned BibTeX to the bibliography. Read the file first with read_file, then replace_in_file anchored on the last entry. Never write_file over an existing bibliography.
4. compile with {} to confirm the file still parses.

If more than three or four entries are missing, this is a sweep, not a gap. Hand off with load_skill and {"id": "oleafly-literature-sweep"} so the papers get source notes and provenance rather than bare entries.

For keys already sitting in unresolvedCites, work out which is true: the entry is missing (add it as above), or the key is misspelled in the prose (fix the prose, do not add an entry to match a typo). search_project with {"query": "<the key>"} shows every use.

Step 5. Write

Use the skeleton in assets/ for your markup. Write with write_file for a new section file, or replace_in_file anchored on the existing section heading for a rewrite. For a rewrite, read_file the current text first: the user's own framing and terminology should survive your edit.

What a paragraph does, in order: name the approach family, say what those works achieve, say precisely what they do not handle, and connect that to this work. The fourth part is what makes it an argument.

Rules that keep it honest:

• Every claim about what a paper does or does not do must come from the source note or the paper itself, not from the title. Titles overstate.
• Cite at the point of the claim, not in a heap at the end of the paragraph. A trailing block of six keys tells the reader nothing about which paper supports which half of the sentence.
• Name a limitation, do not insinuate one. "Does not scale" is a criticism. "Evaluated only up to 10k nodes" is a fact.
• No superlatives about the user's own work in this section. It positions; it does not sell.
• Do not summarise a paper you have not read past its abstract. If the reading list marks it to read, either read it with read_file on its source note, or leave the claim general enough to be supported by the abstract.
• Keep the user's terminology. If they call it a "manifold prior" throughout, do not switch to "geometric prior" here.

Write the section, then reread it once asking a single question: if these paragraphs were deleted, what would the reader not understand about the contribution? If the answer is nothing, the section is a list and needs the fourth part of each paragraph.

Step 6. Compile and verify

1. compile with {}. On failure, get_log with {}, fix, compile again.
2. project_map with {}. unresolvedCites must be empty. If it is not, every key in it is either a missing entry or a typo, and both are yours to fix.
3. get_pdf_text with {}. Read the rendered section. This is the step that catches what compiles but is wrong: a citation rendering as [?], an entry rendering with the wrong year, a paragraph that ran to three pages, a bibliography that lost an author list.

A citation that resolves at compile time can still render as a question mark if the bibliography style dropped the entry. The PDF text is the only place that shows up.

Step 7. Hand off

• The prose needs a quality pass for structure, hedging and reporting standards: load_skill with {"id": "scientific-writing"}.
• The claims in the section need auditing against their sources one by one: load_skill with {"id": "oleafly-verify-claims"}.
• More papers are needed than the gaps you closed: load_skill with {"id": "oleafly-literature-sweep"}.
• The evidence in a specific paper needs appraising before you can characterise it fairly: load_skill with {"id": "scientific-critical-thinking"}.

Failure handling

Done when

• Every citation key in the section appears in bibKeys.
• unresolvedCites is empty.
• Every entry added this session came from verify_citation.
• Each paragraph names an approach family, what it achieves, what it does not handle, and how that connects to this work.
• The themes narrow toward the contribution, and the last one is the closest.
• compile is green and the rendered section in get_pdf_text shows no [?] and no missing bibliography entries.
• The section fits the length the user asked for.

Reference files

• references/structure.md covers grouping patterns, paragraph shapes, and the failure modes of each.
• references/citation-syntax.md covers cite commands per engine and how to detect which one the project uses.
• assets/related-work-skeleton.tex, .typ and .md are starting skeletons.

From a terminal

Outside the app (a terminal, or a coding agent with a shell), the oleafly command does the same work. Always pass --json and check ok.