/sota-writer

name: sota-writer
description: >
  Write structured State-of-the-Art (SOTA) reviews / literature reviews
  for academic research projects with **zero hallucinated citations**.
  Activate this skill whenever the user wants to write, update, or
  expand a SOTA. Triggers (FR + EN) : "écris un SOTA", "état de l'art
  sur", "revue de littérature", "mise à jour SOTA", "survey sur",
  "nouveau SOTA", "write a SOTA on", "literature review on",
  "state-of-the-art review", "/paper-trail:new-sota". **MANDATORY** :
  this skill enforces an INVERTED workflow (research first → read
  validated PDFs → write). It REFUSES to write from memory to prevent
  the kind of citation hallucinations (inverted attributions, fabricated
  quotes) that led to retracted papers in the past. Make sure to use
  this skill whenever any SOTA work is requested, even if the user
  doesn't explicitly say "use sota-writer".

Skill : SOTA Writer (research-first, anti-hallucination)

Why this skill exists

Citation hallucinations in academic writing are systemic when the author writes from memory and looks up sources afterward. They include inverted attributions ("X proved Y" when X proved ¬Y), fabricated quotes (text in quotation marks that doesn't appear in the cited source), wrong attributions (citing the wrong author for a known result), and confusion between similar-named papers (homonymy).

The plugin paper-trail exists because a retracted paper in 2026-02 contained 12 such errors, signaled by the misrepresented author themselves. This skill encodes the **inverted workflow** : research → read → write. Slower in appearance, faster in practice : no post-submission audit, no remediation, no reviewer embarrassment.

Scope

• **Vault root** : `$RESEARCH_VAULT_PATH` (resolved via the adapter,

default obsidian)

• **Registry** : `$RESEARCH_REGISTRY_PATH/refs/*.md` (one `.md` file

per ref with YAML frontmatter)

• **SOTA output location** : resolved via

`adapter.sota_output_path(topic_slug)`

The supreme rule

**No claim in a SOTA without pointing to the notes body of a ref file in state `page1_validated` (or higher).** If I want to write X but no source supports X → either I find one, or I don't write X. No rhetorical rephrasing to "keep" an unsourced claim.

Mandatory 4-phase workflow

A. EXHAUSTIVE RESEARCH
   ├─ paper-search MCP (search_papers multi-source, 22 platforms)
   ├─ rtfm_search (optional — local indexed corpus if configured)
   ├─ NotebookLM (optional — books corpus if RESEARCH_ENABLE_NOTEBOOKLM=1)
   ├─ WebSearch (course pages, personal pages, archive.org)
   └─ → N candidate refs in state `candidate` (file `.md` created for each)

B. ACQUISITION + PAGE 1 VALIDATION
   ├─ Delegate to pdf-cascade skill (paper-trail)
   ├─ 10-source cascade (up to 17 with browser + opt-in routes) + mandatory
   │  page 1 anti-homonymy validation
   └─ → refs in state `page1_validated` (physical PDF + validated)

C. READING / EXTRACTION
   ├─ For each ref in `page1_validated` : read abstract + relevant sections
   ├─ Notes written in the markdown body of the ref file (under frontmatter)
   └─ → structured notes corpus (direct input for writing phase)

D. WRITING FROM NOTES ONLY
   ├─ Each citing sentence points to its ref file via wikilink
   ├─ Each cited ref transitions to `sota_cited_confirmed` as it's used
   ├─ If I want to write X and no note supports X :
   │     either return to phase A (find a source that says X)
   │     or don't write X
   └─ → publishable SOTA (all citations in `sota_cited_confirmed`)

Phase A — Exhaustive research

Pre-flight (mandatory, fast)

Before issuing any search call, run :

python3 -m pipeline preflight

If it reports `paper-search MCP non enregistré`, **stop and ask the user to install it** — the recipe is printed in the preflight output. Do NOT fall back to other searches without notifying the user : the cascade and downstream phases need the unified multi-platform API.

Tools by question type

| Question type | Priority tool | |---------------|---------------| | General academic papers | `mcp__paper-search__search_papers` (multi-source unified) | | Recent preprints (CS, AI, NLP) | `mcp__paper-search__search_arxiv` | | Formal linguistics, NLP | `mcp__paper-search__search_semantic` | | Medical / biomedical | `mcp__paper-search__search_pubmed` | | Cross-domain aggregator | `mcp__paper-search__search_openalex` | | Lookup by exact DOI | `mcp__paper-search__get_crossref_paper_by_doi` | | Local project corpus | `mcp__rtfm__rtfm_search`, `mcp__rtfm__rtfm_context` | | Books (theory, domain-specific) | `mcp__notebooklm__notebook_ask` (if configured) | | Course pages, personal sites | `WebSearch` |

Correct call signatures (avoid TypeError)

The unified `search_papers` tool expects `max_results_per_source`, NOT `max_results` :

mcp__paper-search__search_papers(
    query="your topic",
    max_results_per_source=10,
    sources=["openalex", "crossref", "semantic", "arxiv"],
)

Per-platform tools (`search_arxiv`, `search_semantic`, etc.) typically accept `max_results` directly. When in doubt, omit the limit on the first call and inspect the response shape.

Phase A output

For each identified ref, create a file `$RESEARCH_REGISTRY_PATH/refs/{author_year_short}.md` :

---
uid: bibkey:author2020topic   # provisional, pdf-cascade will resolve to doi:/arxiv:/etc.
author: Author
year: 2020
title: Paper title (as best known)
state: candidate
cited_in:
  - {type: sota, name: SOTA_Current_Draft, section: "draft"}
state_history:
  - {state: candidate, at: <ISO>, by: sota-writer, meta: {search_source: paper-search}}
---

<!-- Body empty in phase A — filled in phase C after PDF read -->

Filtering candidates : >30% DROP refusal

If more than 30% of candidate refs fail to reach `page1_validated` (after phase B), the skill **refuses to write the SOTA** and reports the candidates dropped + reason. The user must then either : -