Compile Resolve

What you produce

A single JSON file at out_path with this shape:

{
  "generated_at": "2026-04-06T...Z",
  "inputs": {
    "fragment_files": ["store/queries/_dev_extract/PMC10103184.fragments.json", "..."],
    "wiki_index": "store/wiki/index/master.md",
    "wiki_existing_entity_count": 0
  },
  "resolutions": [
    { "source_pmc": "PMC...", "hint_type": "cohort | institution | investigator | platform | protocol", "hint_name": "...",
      "classification": "NEW | MERGE_INTO | AMBIGUOUS",
      "proposed_entity_id": "...",            // NEW only
      "proposed_canonical_name": "...",       // NEW only
      "proposed_aliases": ["..."],            // NEW only
      "target_entity_id": "...",              // MERGE_INTO only
      "candidates": ["...", "..."],           // AMBIGUOUS only
      "back_references": [
        {"from": "<cohort_id>", "to": "<linked_id>", "relation": "<closed enum below>"}
      ],
      "confidence": "high | medium | low",
      "reason": "one sentence" }
  ]
}

Three rotating example resolutions

The shape above is constant. The three examples below show the same shape against the locked A/B/C example rotation in .claude/rules/example-rotation.md.

Example A — neuro fluid biomarker (NEW cohort with linked back-references).

{ "source_pmc": "PMC...", "hint_type": "cohort",
  "hint_name": "ADNI Phase 1 serum lipidomics cohort",
  "classification": "NEW",
  "proposed_entity_id": "adni-phase1-serum-lipidomics",
  "proposed_canonical_name": "ADNI Phase 1 serum lipidomics cohort",
  "proposed_aliases": ["ADNI UC Davis lipidomics"],
  "back_references": [
    {"from": "<cohort_id>", "to": "usc-loni-data-coordinating-center", "relation": "parent_institution"},
    {"from": "<cohort_id>", "to": "<assay platform slug>", "relation": "assay_platform"},
    {"from": "<cohort_id>", "to": "michael-weiner-ucsf", "relation": "lead_pi"}
  ],
  "confidence": "high",
  "reason": "Phase + sample medium + assay are explicit, slug is unambiguous." }

Example B — oncology tissue genomics (MERGE_INTO across two papers on the same TCGA project).

{ "source_pmc": "PMC...",  "hint_type": "cohort",
  "hint_name": "TCGA-LUAD bulk RNA-seq cohort",
  "classification": "MERGE_INTO",
  "target_entity_id": "tcga-luad-rnaseq",
  "back_references": [],
  "confidence": "high",
  "reason": "Same TCGA-LUAD RNA-seq cohort already in the wiki from a prior paper; this paper adds proteomics co-modality evidence to the existing entity. Surface tumor purity drift across the two papers as an open question for merge." }

Example C — microbiome stool sequencing (AMBIGUOUS investigator collision).

{ "source_pmc": "PMC...", "hint_type": "investigator",
  "hint_name": "R. Xavier",
  "classification": "AMBIGUOUS",
  "candidates": ["ramnik-xavier-broad", "raul-xavier-monash"],
  "back_references": [],
  "confidence": "low",
  "reason": "Two existing investigator entities with the same surname initial. Affiliation block in this paper just says 'IBD consortium'; cannot disambiguate without the corresponding-author block. Defer to lint." }

Across the three examples the schema is identical. If your output uses ADNI vocabulary on a TCGA paper, or "lipidomics" on a stool paper, the slug rules below are wrong — re-read the input fragment and let the hint's actual surface drive the slug.

Classifications

Every hint gets exactly one of:

• NEW: this entity is not in the wiki. Propose proposed_entity_id, proposed_canonical_name, proposed_aliases. The merge phase will create the entity article.
• MERGE_INTO: this hint refers to an existing wiki entity. Set target_entity_id to the existing slug. The merge phase will integrate this paper's fragments into the existing article.
• AMBIGUOUS: you cannot decide between NEW and a specific existing entity, or between two existing entities. Set candidates to the slugs you cannot pick between. The merge phase will SKIP these and emit them to a review queue. Do not guess.

Slug rules (for NEW only)

You propose the slug. Merge does not invent one. Consistent slugs are what make the wiki idempotent across runs.

• All lowercase. Hyphens between words. ASCII only. No leading or trailing hyphen.
• Cohort: <study>-<wave>-<sample>-<assay> when known. Drop fields you do not know rather than inventing them. Worst case fall back to <first-author-lastname>-<institution-short>-<year>-<indication>. Examples (one per A/B/C): A adni-phase1-serum-lipidomics. B tcga-luad-rnaseq or tcga-luad-wes. C prism-ibd-baseline-shotgun.
• Institution: short canonical, drop "the", "of", department suffixes unless load-bearing. Examples: A usc-loni-data-coordinating-center. B mskcc-tissue-procurement-core. C broad-institute-microbiome.
• Investigator: <first>-<last>-<primary-affiliation-short>, where primary-affiliation is the investigator's HOME institution as stated in the affiliation block, NEVER the cohort or consortium they appear in. The canonical counter-example: Michael Weiner is michael-weiner-ucsf, NOT michael-weiner-adni, even when the paper is about ADNI. If the affiliation field names a consortium (ADMC, TCGA, IBDMDB, etc.) and not a home institution, fall back to the corresponding-author affiliation in the paper frontmatter. Rotating examples: A michael-weiner-ucsf. B matthew-meyerson-broad (NOT matthew-meyerson-tcga). C ramnik-xavier-broad (NOT ramnik-xavier-ibdmdb).
• Platform: <vendor-or-site>-<technique>. Examples: A uc-davis-lipidomics-uhplc-qtof or nightingale-nmr. B illumina-truseq-rna-exome or agilent-sureselect-xt-low-input. C illumina-novaseq-shotgun-metagenomics or qiime2-dada2-16s-v4.
• Protocol: <institution>-<sample>-<assay> linked to the cohort that uses it.
• Bundle: handled by the bounty formatter, not resolve. Skip.

Back references

Whenever you classify a cohort hint as NEW or MERGE_INTO, also emit back_references for each linked entity (institution, investigator, platform, protocol). Format: {"from": <cohort_id>, "to": <other_id>, "relation": <one of the values in the closed enum below>}.

Relation enum (closed list, anything outside is rejected by merge):

• parent_institution — the institution that owns or governs the cohort. A: ADNI → USC LONI. B: TCGA-LUAD → NCI/GDC. C: IBDMDB → Broad Institute.
• sponsor — funder or sponsoring consortium. A: ADMC, NIA. B: NCI Cooperative Group, industry sponsor. C: Helmsley Charitable Trust, Crohn's & Colitis Foundation.
• data_provider — institution or consortium that distributes the data, distinct from the physical collection site.
• collection_site — the institution that physically held the samples (clinic, hospital, biobank, processing core).
• assay_platform — the analytical platform or instrument used to generate the data. A: targeted lipidomics LC-MS/MS, UHPLC-QTOF, NMR. B: bulk RNA-seq exome capture, WES, methylation array. C: 16S V4 sequencing, shotgun metagenomics, untargeted metabolomics on stool.
• lead_pi — the principal investigator who led the cohort or the paper.
• co_investigator — other named investigators on the paper.
• collection_protocol — link to a protocol entity describing the operational steps.
• related_trial — link to a trial entity (NCT ID).

A single linked entity gets ONE relation, the most specific one. An institution that ran the assay is assay_platform if the entity is the instrument, collection_site if the entity is the lab. Pick the one the paper actually evidences. If a hint anchors a cohort in two distinct ways (a consortium that is BOTH sponsor and data provider), emit two back_references with two different relations.

Merge applies these to the linked entity's referenced_by list.

You only emit back references for entities you have ALSO classified in this same plan (either NEW, MERGE_INTO, or already in the wiki). Do not emit back references to entities that are AMBIGUOUS — wait until they are resolved.

Hard rules

1. Dry run. You write only the resolution_plan.json. You do not touch store/wiki/. If you find yourself wanting to write an entity article, stop and emit a NEW classification instead.
2. Same hint name across papers does NOT mean same entity. A university name appearing in two papers from different departments might be the same institution OR different sub-units. If the wiki already has the parent slug, MERGE_INTO. If not, treat the second occurrence as MERGE_INTO the NEW one you proposed for the first paper IN THIS SAME PLAN. Order matters: process fragment files in input order; the plan accumulates as you go.
3. Same surname investigator at the same institution → MERGE. Different institutions → AMBIGUOUS. The wiki cannot disambiguate two same-name same-institution PIs, so the slug rule already encodes the disambiguation.
4. Cohort granularity is a judgment call. Two collections from the same parent study but with different sample medium, assay platform, or wave are SEPARATE cohorts. (A) ADNI Phase 1 serum lipidomics vs ADNI Phase 2 untargeted metabolomics. (B) TCGA-LUAD WES vs TCGA-LUAD RNA-seq vs TCGA-LUAD methylation. (C) HMP1 healthy stool vs HMP2 IBD stool. The same cohort appearing in two papers with the same medium and platform is ONE entity. When in doubt, MERGE and let lint split later — splitting is cheaper than de-duping.
5. Never propose slugs for entities the wiki already has. Always reuse the existing slug.
6. Confidence is mandatory. high = unambiguous match or clean NEW. medium = small terminology mismatches but the resolution is defensible. low = ambiguous, prefer AMBIGUOUS over a low-confidence MERGE_INTO.

What you do NOT do

• Do not write entity articles.
• Do not modify the wiki index.
• Do not deduplicate fragments. The fragments inside each fragment file are merge's problem.
• Do not read entity article bodies. Index summary line is the only allowed signal.
• Do not search the web or call tools.

Ordering

Process fragment files in the order they were passed to you. Within a single fragment file, process entity hints in this order: institutions → investigators → platforms → protocols → cohorts → trials_referenced. This way, when a cohort is resolved, the institutions and platforms it depends on already have proposed slugs, and the back_references can reference them by ID.

When the wiki is empty

First compile pass: every hint is NEW. The plan is essentially a list of slug proposals. This is the cheap case. The interesting cases (MERGE_INTO, AMBIGUOUS) only show up on subsequent passes or within a multi-paper plan where later papers can reference slugs proposed by earlier papers.

Length budget

A typical plan for 3 papers produces 15 to 40 resolutions. If you are emitting more than 60, you are over-splitting cohorts. If fewer than 10, you are under-counting institutions and investigators.