lit-review

Conduct a literature search and deliver a structured scientific briefing. See REFERENCE.md for mode-specific guidance.

On invocation, ask the user

1. Topic — what are we searching for?
2. Mode — frame / methods / interpret / landscape / synthesize
3. Starting point (optional) — any known papers, authors, or search terms to seed from?

Search order

1. Zotero — existing library first; note what's already there
2. Consensus — synthesized search for landscape and key claims
3. Google Scholar — seminal works, citation counts, author networks
4. arxiv / bioRxiv — recent and unpublished work

Stop adding sources once coverage is sufficient for the mode.

Output structure

1. High-level summary — 1–2 paragraphs: what the field looks like, what is settled, what is contested. Tag findings as established / debated / emerging throughout.

2. Topical review — key ideas, findings, and debates organized by theme. Apply mode-specific guidance from REFERENCE.md. Distinguish what is well-established, actively debated, and absent.

3. Papers — for each paper:

• Full citation (authors, year, title, journal/venue)
• Peer-reviewed or preprint — flag explicitly
• Key contribution in 1–2 sentences
• Relevance to the current topic and mode

4. Offers — always prompt:

• Save to REFERENCES.md? — check if it exists and show existing entries first. Append using the template in REFERENCE.md. Never overwrite.
• Add to Zotero? — list papers not already in the library, then ask. If yes, execute the steps below.

Adding papers to Zotero

Required env vars (set in ~/.claude/settings.json → env block):

• ZOTERO_USER_ID — your numeric Zotero user ID (find it at zotero.org/settings/keys)
• ZOTERO_API_KEY — a Zotero API key with write access (same page)
• ZOTERO_INBOX_COLLECTION — name of the collection to file new papers into (e.g. Inbox)

If any required var is unset, skip the Zotero write step and tell the user what to configure.

Step 1 — resolve the collection key:

curl -s "https://api.zotero.org/users/$ZOTERO_USER_ID/collections?limit=100" \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  | python3 -c "
import sys, json, os
cols = json.load(sys.stdin)
target = os.environ.get('ZOTERO_INBOX_COLLECTION', 'Inbox')
for c in cols:
    if c['data']['name'] == target:
        print(c['key'])
"

Step 2 — POST items. Build a JSON array; one object per paper. Use itemType journalArticle for peer-reviewed, preprint for arxiv/bioRxiv. Include collections: [\"<KEY>\"] from Step 1.

Minimum required fields per item:

• itemType, title, date
• creators: [{"creatorType": "author", "firstName": "...", "lastName": "..."}]
• DOI or url (include both when available)
• collections: ["<inbox-key>"]
• tags: [{"tag": "lit-review"}]

curl -s -X POST "https://api.zotero.org/users/$ZOTERO_USER_ID/items" \
  -H "Zotero-API-Key: $ZOTERO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '<JSON array>'

Step 3 — report results. Parse the response: list titles that succeeded (HTTP 200 success key) and any that failed (failed key). A paper already in the library does not need to be re-added.