lit-sync

Files (10)

• SKILL.md
• bbt_lookup.md · references/
• concept_note_template.md · references/
• fulltext_report.md · references/
• note_templates.md · references/locale/ko/
• check_citekey_provenance.py · scripts/
• skill.yml
• citekey_provenance_challenge.sh · tests/
• citekey_provenance_challenge_selftest.sh · tests/
• test_poll_logic.sh · tests/

SKILL.md (first lines)

# Literature Sync: Zotero + Obsidian Pipeline

Takes the `.bib` output of `/search-lit` (or any user-specified .bib file), synchronizes the
references into the Zotero library and Obsidian literature notes, and extracts cross-cutting
concept notes once enough literature notes accumulate.

## Prerequisites

- **Project owner only.** Collaborators consume the committed `manuscript/_src/refs.bib` snapshot
  read-only. If the current user is a collaborator (no Zotero access per `SSOT.yaml`
  `reference_manager.required_for`), abort with instructions to flag `[@NEW:topic]` placeholders in
  the manuscript and notify the owner.
- Zotero desktop 7.x + Better BibTeX plugin, with Better BibTeX "Keep updated" auto-export
  configured to `<project>/manuscript/_src/refs.bib`.
- Zotero MCP server (if not connected, skip Phase 2; auto-export still refreshes once Zotero is
  reopened).
- Obsidian CLI or direct file writing to the vault; vault path from the user's environment
  (e.g., `$OBSIDIAN_VAULT`).

## Artifact Contract

`/lit-sync` is the **sole writer** of `manuscript/_src/refs.bib` (via the Better BibTeX auto-export
trigger), `references/zotero_collection.json`, and `references/fulltext_retrieval.json` (Phase 2.7).
**NEVER write `refs.bib` directly** — not even to compensate for a missing Zotero connection —
because only Better BibTeX's export keeps it in step with the library; if auto-export is broken, fix
the Zotero setup. Direct hand edits to `refs.bib` are drift — revert on sight.

---

## Phase 1: Parse BibTeX

Parse the user-specified `.bib` file, or the `references/library.bib` just produced by
`/search-lit`, with regex. Extract per entry: citekey, doi, pmid, title, authors (first + last
minimum), journal, year, and volume/number/pages if present. Log any parse failures and skip those
entries. All bibliographic data in later phases comes from these entries or from API responses.

A parsed citekey is not yet a library key: `/search-lit` candidate keys (`Kim_2024_Validation`) are
provisional, and Better BibTeX mints the real key when Phase 2 adds the item. Never compose a key;
Step 3.2 §Citekey provenance says where the note's key comes from.

---

## Phase 2: Zotero Sync

If the Zotero MCP is not connected, skip this phase (still write the Step 2.3 file with
`status: "skipped"`) and proceed to Phase 3.

### Step 2.1: Determine project collection

Identify the project from the current working directory or an explicit user override. Reuse a
recorded collection key; otherwise check existing Zotero collections for the project and, if none
exists, create one with `zotero_create_collection`. Record the collection key, and report it to the
user when a new collection is created.

### Step 2.2: Dedupe + add

For each entry:

1. Use `zotero_search_items` to search by DOI or title — if already present, skip.
   This search-first step is what prevents duplicates; `zotero_add_by_doi` does **not**
   dedupe by itself (it fetches CrossRef and creates the item), so never skip the search.
2. Otherwise call `zotero_add_by_doi` (when a DOI is available) or `zotero_add_by_url` (the PubMed
   URL, when only a PMID is available). An entry with neither DOI nor PMID is not added: count it
   as failed and ask the user to add it manually.
   - `zotero_add_by_doi` accepts an `attach_mode` argument that governs the **OA child-PDF
     attach attempt at add time** (the installed server treats `linked_url` as "bookmark the
     PDF URL"; other values download/import). Exact accepted values are server-version-specific —
     verify against the connected server. Do **not** use `zotero_add_from_file` to attach a PDF to
     an item added here: it has no parent-item argument and would create a duplicate parent item.
3. Use `zotero_manage_collections` to place the item in the project collection.

### Step 2.3: Result report

```
Zotero Sync:
  Added:     8 papers (new)
  Skipped:   3 papers (already in library)
  Failed:    1 paper (no DOI/PMID)
  Collection: RFA-Meta (TZQEP4NH)
```

Always write `references/zotero_collection.json` in the project workspace:

```json
{
  "schema_version": 1,
  "status": "synced",
  "collection": "RFA-Meta",
  "collection_key": "TZQEP4NH",
  "added": 8,
  "skipped": 3,
  "failed": 1
}
```

If Zotero is unavailable, write the same file with `status: "skipped"` and a
human-readable `reason`.

---

## Phase 2.5: refs.bib snapshot refresh

Better BibTeX "Keep updated" auto-export normally refreshes `manuscript/_src/refs.bib` within
seconds of a Zotero change. This phase **verifies** the snapshot actually updated before downstream
skills consume it.

### Step 2.5.1: Resolve path

Read `SSOT.yaml` → `truth.refs_bib`. Default: `manuscript/_src/refs.bib`. If absent (legacy project), fall back to `manuscript/_src/refs.bib` and emit a WARN recommending SSOT migration.

### Step 2.5.1b: Precondition assertion (early-exit, do NOT poll)

Before entering the 10s polling loop in Step 2.5.2, verify both preconditions. If **either** fails, abort Phase 2.5 with setup instructions instead of waiting for a timeout that will never resolve.

1. **Better BibTeX is answering.** Probe the running plugin, not a file on disk:

   ```bash
   curl -s -m 5 -o /dev/null -w "%{http_code}" \
     http://127.0.0.1:23119/better-bibtex/json-rpc    # expect 200

From Aperivue/medsci-skills, MIT.

More from Aperivue/medsci-skills