Review Citations

Review Citations

Run bactopia-citations --validate and present the integrity report, then apply fixes on request.

What this covers

Three gaps that the per-component lint rules don't catch:

• Orphan keys: entries defined in data/citations.yml that are never referenced by any @citation tag. Accumulate as tools are replaced or renamed. The CLI suggests candidate "homes" for each orphan based on repo state — use those to decide between wire-up vs. drop.
• Expected orphans: yml entries marked provenance_only: true — foundational tools acknowledged for provenance only (e.g. nextflow, nf-core, nf-test). Surface them as informational, never flag as an issue.
• Workflow missing keys: @citation keys in workflow main.nf files that don't resolve to an entry in citations.yml. The W-series lint rules have no M035/S019 equivalent, so these only surface here.

Module and subworkflow @citation validation is handled by bactopia-lint rules M035 (modules) and S019 (subworkflows) — when the user wants to check those, point them at /review-groovydoc.

Steps

1. Run bactopia-citations --validate via the wrapper, asking for JSON so it's easy to parse:

   bash .agents/skills/review-citations/scripts/run-bactopia-citations.sh \
       --bactopia-path /home/rpetit3/repos/bactopia/bactopia \
       --validate --json --silent

   Exit code is 0 when there are no real orphans and no missing workflow keys (expected orphans alone do not trigger a non-zero exit). Exit 1 when any real issue is found. Both cases print JSON on stdout.

2. Parse the JSON. Shape:

   {
     "orphans": {
       "workflows": [],
       "datasets_ariba": ["srst2"],
       "tools": ["aragorn", "barrnap"]
     },
     "expected_orphans": {
       "influences": ["nfcore"],
       "tools": ["nextflow", "nftest"]
     },
     "potential_homes": {
       "aragorn": [
         {"type": "toolName", "path": "modules/prokka/module.config:30", "hint": "ext.toolName = \"bioconda::prokka=1.15.6\""},
         {"type": "script_token", "path": "modules/prokka/main.nf:55", "hint": "prokka --outdir ..."}
       ],
       "srst2": [
         {"type": "sibling_key", "path": "data/citations.yml (arg_annot)", "hint": "possible duplicate/variant of referenced key 'arg_annot'"}
       ]
     },
     "missing_workflow_keys": [
       {"component": "workflows/foo", "file": "workflows/foo/main.nf", "line": 42, "key": "typoed_key"}
     ],
     "summary": {
       "orphans_total": 3,
       "expected_orphans_total": 3,
       "missing_total": 1,
       "yml_total": 157,
       "referenced_total": 154
     }
   }

   Key fields:

   • orphans — real issues that need user judgment.
   • expected_orphans — provenance_only: true entries; informational only, never a failure.
   • potential_homes[orphan] — heuristic candidates for where each real orphan could be wired. Candidate types: directory, toolName, config_param, script_token, sibling_key (ranked roughly by specificity in that order).
   • missing_workflow_keys — workflow-tier @citation references that don't resolve.

3. Present a summary grouped by issue type:

   • Clean repo (orphans + missing both zero): report "All <yml_total> citations are referenced, <expected_orphans_total> provenance-only acknowledged" and list the expected-orphan keys inline as a dim note. Stop there.

   • Issues found: show sections in this order:

     1. Orphans — per orphan, render the key with its top 2-3 potential_homes candidates inline. Lead with the most specific candidate (directory > toolName > config_param > script_token > sibling_key). Example:

        aragorn (tools) — candidates:
          • toolName: modules/prokka/module.config:30  ext.toolName = "bioconda::prokka=1.15.6"
          • script_token: modules/prokka/main.nf:55  prokka --outdir ...

     2. Missing workflow keys — component, file:line, bad key.

     3. Expected orphans — single dim line listing the keys so the user knows they exist but aren't flagged.

     Lead with whichever of (1) or (2) has more items. Keep the output scannable; if there are many orphans, show counts + top 5-10 with homes, then note the rest by count.

4. If the user asks to fix issues, walk through them one category at a time. Orphans and missing keys need different treatment, so don't batch them together.

Fixing orphans (three sub-cases)

Orphans need per-key judgment — don't sweep them. For each real orphan, decide between three actions:

• Wire up: The orphan has a plausible home in potential_homes. Edit the target main.nf to append the orphan key to its @citation line (keep existing cites first, append new keys). Verify the result with the Edit tool — if the current @citation line is * @citation prokka, the updated line becomes * @citation prokka, aragorn.

• Drop: Truly retired — no home, no sibling, no future plans. Use the Edit tool to delete the key line plus its entire indented block in data/citations.yml (typically 4-6 lines; cite: | multi-line bodies run longer).

• Keep with provenance marker: The orphan is deliberately unreferenced (foundational tool, planned but not yet wired, retained for historical record). Add provenance_only: true to its yml block — this moves it into expected_orphans on the next run so it stops tripping the validator. Place the field right below name:. Example:

  nextflow:
    name: Nextflow
    provenance_only: true
    link: ...
    cite: |
      ...

Every citations.yml entry shape:

aragorn:
  name: Aragorn
  link: ...
  description: ...
  cite: |
    Citation text across one or more lines.

Keys live under six top-level sections: workflows, datasets_ariba, datasets_generic, datasets_minmer, influences, tools. The orphans field in the JSON is already grouped by section — use that grouping so you're editing under the right parent key.

Always confirm before editing. Heuristics produce candidates, not decisions. Present the top suggestion and ask the user to pick wire-up / drop / keep-with-marker.