skill-researcher-litreview

name	skill-researcher-litreview
version	0.1.0
description	Three researcher flows — start a literature review by decomposing it into atomic reading and synthesis tasks, record a paper and its authors as graph facts, or recall the papers an author has written.
neurotypes	[]
status	stable
triggers	[{"phrase":"start a lit review on"},{"phrase":"start a literature review on"},{"phrase":"begin a lit review on"},{"phrase":"begin a literature review on"},{"phrase":"add a paper:"},{"phrase":"record a paper:"},{"phrase":"recall papers by"},{"phrase":"what has","note":"only when followed by ' written' or ' published'"},{"phrase":"papers by"}]
mcp_dependencies	[{"server":"neurodock-task-fractionator","tools":["decompose"]},{"server":"neurodock-cognitive-graph","tools":["recall_entity","record_fact"]}]
profile_dependencies	["preferences.output_format","preferences.max_chunk_size"]
license	AGPL-3.0-or-later
authors	["NeuroDock contributors"]

skill-researcher-litreview

Three flows for someone running a literature review: break a topic into atomic reading and synthesis tasks, record a paper and its authorship so the graph remembers it, and ask the graph what a given author has written. The trigger phrases are unambiguous on purpose — they will not steal activation from adhd-daily-planner, the eng-manager-1on1 decomposition flow, or any general-purpose recall.

This skill supports the act of reading and synthesising deeply. It is not a tool for consuming more papers per hour. It does not summarise abstracts, does not generate "key insights" from titles, and does not invent papers an author did not write. The deliverables are scaffolding for your own reading and your own synthesis — not a substitute for either.

This skill is also not a citation manager. It does not export BibTeX, does not store PDFs, does not deduplicate against a remote catalogue, and does not integrate with Word or LaTeX. Use Zotero, Mendeley, or Paperpile for those jobs. The graph here remembers paper + author + authorship as plain facts so the skill can recall what you have recorded — that is its only scope.

When to activate

Activate when the user's message contains one of the trigger phrases verbatim. The trigger phrase determines which of the three flows runs:

• start a lit review on <topic> / start a literature review on <topic> / begin a lit review on <topic> / begin a literature review on <topic> → Flow A: lit-review decomposition.
• add a paper: <title>, <authors>, <year> / record a paper: <title>, <authors>, <year> → Flow B: record paper.
• recall papers by <author> / papers by <author> / what has <author> written / what has <author> published → Flow C: recall by author.

Do not activate on partial matches (I might do a lit review someday), past tense (I started a lit review last month), or generic literature mentions (literature shows that...). Do not activate if another skill is already running its flow in this turn; let it finish.

Flow A — lit-review decomposition

The user says some variant of start a lit review on embodied cognition in HCI. Goal: a list of atomic reading and synthesis tasks that scaffold the review, generated by neurodock-task-fractionator. No invented seed papers, no opinions about the field.

1. Parse the topic. Everything after on is the topic. Trim. Treat the parsed string verbatim — do not normalise capitalisation, do not expand abbreviations (HCI stays HCI).

2. Call decompose. Pass the topic as a literature-review goal with a working time budget. Default budget: P10D (ten working blocks of 4h, ≈ 40h of reading and synthesis). The task-fractionator interprets P10D per ADR 0003 §3.

   The goal argument is a structured prompt that asks for atomic reading and synthesis tasks specifically. Verbatim:

   Literature review on: <topic>. Break this into atomic reading and synthesis tasks. Include tasks for identifying seed papers, reading in batches, extracting claims, mapping disagreements between sources, and synthesising themes. Do not invent paper titles or author names.
   

3. Three outcomes from decompose:

   • Success — a list of atomic tasks, each with at least one acceptance criterion. Continue to step 4.
   • BUDGET_INFEASIBLE — surface the error message as one line: The topic is broader than fits in the default budget. Try a narrower scope, or pass a longer time budget. Stop.
   • DECOMPOSITION_UNAVAILABLE or any other error — surface the error code on one line. Stop.

4. Render the task list. See "Output format — Flow A" below.

5. Stop. Do not propose seed papers, do not name authors, do not editorialise about the topic ("rich literature", "well-studied area"). The task list is the deliverable; finding the actual papers is the user's first task.

Flow B — record a paper

The user says add a paper: <title>, <authors>, <year>. Goal: persist the paper, each author, and the authorship relationships as facts in the cognitive graph. No invention beyond what the user typed.

1. Parse the input. Split the string after add a paper: (or record a paper:) on commas. The grammar:

   add a paper: <title>, <author_1> [and <author_2> [and <author_3>...]], <year>
   

   • The first comma-delimited segment is the title. Strip whitespace. Treat the title verbatim — do not normalise capitalisation.
   • The last comma-delimited segment is the year. Must parse as a 4-digit integer between 1500 and the current year + 1; otherwise abort with: I could not parse a year from the last segment. Try: "add a paper: <title>, <author>, <year>".
   • Everything between is the authors segment. Split it on the literal word and (with spaces) to get the individual author strings. If the segment contains no and, treat the whole thing as a single author.

2. Validate. If the title is empty, the authors list is empty, or the year is missing or unparseable, abort with the corresponding one-line error and stop. Do not call any tool.

3. Record the paper entity. Call record_fact once to tag the paper:

   {
     "subject": { "type": "concept", "name": "<title>" },
     "predicate": "tagged",
     "object": { "literal": "paper" }
   }
   

   We use type: "concept" for the paper because the v0.1.0 entity-type vocabulary does not include a dedicated "paper" type; concept is the closest fit and the tagged: paper fact makes the role explicit. (See "Decisions flagged" in README.md.)

4. Record the year. Call record_fact once more to tag the year on the same paper subject:

   {
     "subject": { "type": "concept", "name": "<title>" },
     "predicate": "tagged",
     "object": { "literal": "year:<year>" }
   }
   

5. Record each author and the authorship relationship. For each author parsed in step 1, call record_fact once:

   {
     "subject": { "type": "concept", "name": "<title>" },
     "predicate": "belongs_to",
     "object": { "type": "person", "name": "<author>" }
   }
   

   This creates the author entity (auto-created by record_fact per the v0.1.0 contract) and the authorship edge. The semantic of belongs_to here is "the paper belongs to the authors who wrote it" — the closest fit in the v0.1.0 eight-predicate vocabulary.

6. Render the confirmation. See "Output format — Flow B" below.

7. Stop. Do not ask for an abstract, do not ask for a DOI, do not ask for a venue. The skill records only what the user typed. If the user wants richer metadata, that is Zotero's job.

Flow C — recall papers by author

The user says recall papers by <author>. Goal: ask the graph for everything that author has been recorded as authoring, then render a bibliography. No paper appears in the output that is not in the graph's response.

1. Parse the author name. Everything after by (for recall papers by and papers by) or between what has and written/ published is the author. Trim. Treat verbatim.

2. Recall the entity. Call recall_entity({ "name_or_alias": "<parsed name>" }).

3. Resolution check. If resolution.method is alias, fuzzy, or embedding, surface the resolved entity name and the resolution score before continuing. Ask one question: I read "<parsed name>" as the entity "<resolved>" (<method> match, score <score>). Continue? Wait for confirmation. Do not assume.

4. If entity is null, say so plainly: No author named "<parsed name>" is recorded in the graph. If you've added papers by this author under a different name, try that name. Stop.

5. Filter the neighbours. From recall_entity's neighbours[], keep only entries where relationship == "belongs_to" and the neighbour's entity type is concept. These are the candidate papers — each is a concept entity whose belongs_to edge points to this author.

6. For each candidate paper, find its year by reading the paper's own facts[] for a tagged predicate with object literal matching year:<YYYY>. If no year is recorded, render the year as n.d. (no date). Do not invent a year. If recall_entity does not return paper-side facts (because neighbours are summary entries only), call recall_entity({ "name_or_alias": "<paper title>" }) once per candidate to fetch the year.

7. Render the bibliography. See "Output format — Flow C" below. Order: by year descending, ties broken by paper title ascending.

8. Stop. Do not propose related authors, do not propose related topics, do not summarise the body of work. The bibliography is the deliverable.

Output format

Flow A — lit-review decomposition

Strict "Answer First". First sentence ≤ 100 characters.

Lit-review plan — <topic>. <N> atomic tasks across reading and synthesis.

### Reading
- <task title> (<estimated_minutes> min)
  Acceptance: <first acceptance criterion>
- ...

### Synthesis
- <task title> (<estimated_minutes> min)
  Acceptance: <first acceptance criterion>
- ...

These tasks scaffold your review. I did not pick seed papers or name authors — that's the first task.

Rules:

• Group tasks into ### Reading and ### Synthesis based on tags from decompose (reading, synthesis). If a task has neither tag, place it under ### Reading as a default. If decompose returned no tags at all, render all tasks under a single ### Tasks section instead.
• Task titles and estimates appear verbatim from the decompose result.
• The closing line is mandatory.

Flow B — record paper

Recorded: "<title>" (<year>), by <author_1>[, <author_2>, ... and <author_N>].
Graph entries: 1 paper, <N> author(s), <N+2> facts.

Rules:

• Authors joined with commas, last two joined with and. A single author appears alone.
• The fact count is N + 2 because: 1 tagged: paper, 1 tagged: year:<year>, and N belongs_to edges (one per author).
• No follow-up question. Do not ask Add another? or Want me to tag this with a topic?.

Flow C — recall papers by author

Papers by <author> (<N> recorded):

- <author>. (<year>). <title>.
- <author>. (<year>). <title>.
- <author>. (n.d.). <title>.

These are the papers I have on file for <author>. I did not search anywhere external.

Rules:

• The plaintext citation format is <author>. (<year>). <title>. — one paper per bullet. This is deliberately ad-hoc: see "Decisions flagged" in README.md.
• Ordering: year descending, ties broken by title ascending. Papers with n.d. sort last.
• The closing line is mandatory. It is the user's reminder that the recall is bounded to what was recorded — no external lookup happened.

Empty-recall fallback (entity exists but has no belongs_to paper neighbours):

<author> is in the graph, but no papers are recorded for them yet. Use "add a paper:" to record one.

Hard hallucination guard (Flow C)

The defining failure mode for this skill is a Flow C response that lists a paper the graph did not return. This MUST NOT happen.

• Every line in the bibliography MUST correspond 1:1 with an entry in recall_entity's response filtered per step 5.
• If the response has zero matching entries, emit the empty-recall fallback. Do not list anything.
• If the user pushes back ("you must have more, look harder"), respond with: The graph is what I can see. If a paper is missing, add it with "add a paper:" and it will appear next time. Do not invent.
• Never combine results across recall calls. The bibliography reflects exactly one recall_entity invocation per Flow C turn.

Do not

• Do not invent paper titles, author names, venues, years, DOIs, or abstracts in any flow.
• Do not summarise the abstract or "key contribution" of any paper. This skill records and recalls; it does not analyse.
• Do not propose seed papers in Flow A. The user identifies their own seed papers — that is the first task in the decomposition.
• Do not editorialise about a topic ("foundational work", "active area", "rich literature").
• Do not call decompose outside Flow A.
• Do not call record_fact outside Flow B.
• Do not call recall_entity outside Flow C.
• Do not silently merge author names. If the user adds Bender E. in one session and Emily M. Bender in another, those are two entities until the user explicitly aliases them.
• Do not propose citation export, BibTeX generation, or any integration with reference managers. Tell the user to use Zotero.
• Do not score, rate, or rank authors or papers ("highly cited", "seminal", "influential"). The skill has no basis for any such claim.
• Do not use productivity-theatre vocabulary: consume, crush, power through, read more papers per week, optimise your reading, 10x your literature review.
• Do not activate inside another skill's flow.

What this skill is not

• Not a citation manager. Use Zotero, Mendeley, or Paperpile.
• Not a paper search engine. It does not query Google Scholar, Semantic Scholar, arXiv, or anything else.
• Not a summarisation tool. It does not generate abstracts, key takeaways, or "what this paper is about".
• Not a clinical or coaching tool. It makes no claims about the user's neurotype, reading speed, or capacity.
• Not a productivity hack. It does not help anyone read faster. It helps a careful reader keep track of what they've read and what they intend to read next.

Examples

See tests/:

• tests/01-start-litreview.md — Flow A on "embodied cognition in HCI" with a 10-day decomposition budget.
• tests/02-record-paper.md — Flow B recording a single paper with two co-authors.
• tests/03-recall-by-author.md — Flow C asserting that no paper appears in the output that the graph did not return.