Reference Verification Skill (Double Control)

This produces THREE files:

• <paper>_REFS_TO_VERIFY.json — batched references for sub-agents
• <paper>_REFS.ris — Zotero/Mendeley/EndNote import file
• <paper>_REFS.xlsx — detailed Excel table with all parsed fields + verification columns

Options: --batch-size N (default 10), --ris-only (skip JSON/Excel)

Step 3: Read the JSON and prepare batches

Read _REFS_TO_VERIFY.json using the Read tool. Extract:

• batches[] — each has batch_num, ref_start, ref_end, references[]
• Each reference has num, label, text

Step 4: ROUND 1 — Spawn Sonnet sub-agents (one per batch)

YOU MUST DO THIS. For each batch in the JSON, spawn a Sonnet sub-agent using the Task tool. This is the first verification pass.

Task tool parameters:
  description: "Verify refs {ref_start}-{ref_end} accuracy"
  subagent_type: general-purpose
  model: sonnet
  run_in_background: true

Sub-agent prompt — build this for each batch by inserting the actual references:

You are a reference verification agent (Round 1). For each of the academic
references below, search the web to verify that the reference is ACCURATE —
correct authors, year, title, journal/publisher, volume, issue, pages, and DOI.
Report any errors you find.

For each reference, output a JSON array of objects with these exact fields:
- "ref_num": [the reference number]
- "status": "CORRECT" / "ERROR" / "UNVERIFIABLE"
- "issues": "" if CORRECT, otherwise describe what's wrong and the correct value

Example output:
[
  {"ref_num": 1, "status": "CORRECT", "issues": ""},
  {"ref_num": 2, "status": "ERROR", "issues": "Year should be 1976, not 1979. Publisher is IUP, not Penguin."},
  {"ref_num": 3, "status": "UNVERIFIABLE", "issues": "No book found with this title/publisher online."}
]

Here are the references to verify:

REF{num}: {full reference text}
REF{num}: {full reference text}
...

Search the web for EACH reference individually. Be thorough — check every field.
Output ONLY the JSON array, no other text.

Concurrency rules:

• Launch up to 3 sub-agents in parallel (max concurrent agents limit)
• As each sub-agent completes, launch the next queued batch
• Track progress: show the user which batches are running, done, and queued

Step 5: Collect Round 1 results and update Excel

As each sub-agent returns:

1. Parse the JSON array from its result
2. Merge all batch results into one _AGENT1_FINDINGS.json file
3. Run the Excel updater:

py "C:/Users/user/.claude/skills/ref-verify/ref_verify.py" --update-excel "<paper>_REFS.xlsx" "<paper>_AGENT1_FINDINGS.json" --agent 1

This fills in the "Agent 1 Status" and "Agent 1 Issues" columns in the Excel.

Step 6: ROUND 2 — Spawn a SECOND set of Sonnet sub-agents (double control)

YOU MUST DO THIS. This is the independent second verification pass for double control. Spawn new sub-agents with a slightly different prompt to ensure independent verification:

You are a reference verification agent (Round 2 — independent double-check).
For each of the academic references below, search the web INDEPENDENTLY to verify
accuracy. Check: authors (all of them, correct initials), year (original vs reprint),
title (exact wording), journal/publisher, volume, issue, pages, DOI.

Pay special attention to:
- Original publication year vs. reprint/translation year
- Correct publisher for the specific edition cited
- All author initials (not just surname)
- Chapter references: verify the book title AND editors

For each reference, output a JSON array:
[
  {"ref_num": 1, "status": "CORRECT", "issues": ""},
  {"ref_num": 2, "status": "ERROR", "issues": "Specific description of what's wrong"}
]

References to verify:

REF{num}: {full reference text}
...

Search the web for EACH reference. Output ONLY the JSON array.

Same concurrency rules as Round 1.

Step 7: Collect Round 2 results and update Excel

1. Merge Round 2 results into _AGENT2_FINDINGS.json
2. Update Excel:

py "C:/Users/user/.claude/skills/ref-verify/ref_verify.py" --update-excel "<paper>_REFS.xlsx" "<paper>_AGENT2_FINDINGS.json" --agent 2

This fills "Agent 2 Status" / "Agent 2 Issues" columns AND computes the "Final Status":

• Both agree → Final = their shared status
• Either says ERROR → Final = ERROR
• Disagreement → Final = REVIEW (needs manual check)

Step 8: Present final summary table

When ALL agents are done, present a complete summary:

First, show only the issues (where Final Status is not CORRECT):

## Issues Found (Double Control)

| # | Reference | Agent 1 | Agent 2 | Final | Issue |
|---|-----------|---------|---------|-------|-------|
| 3 | Beck (1979) | ERROR | ERROR | ERROR | Year should be 1976, publisher IUP |
| 13 | Ferenczi (1932) | ERROR | ERROR | ERROR | Published 1988, not 1932 |
| 54 | Rachman (1972) | UNVERIFIABLE | UNVERIFIABLE | REVIEW | No book found |
| 60 | Shephard (2001) | CORRECT | ERROR | ERROR | Agent 2 found publisher discrepancy |

Then the clean count:

Double-control verified: 66 of 74 correct (both agents agree).
Issues requiring attention: 8

Classify issues by agreement:

1. Both agree ERROR — high confidence there's a real mistake
2. Both agree UNVERIFIABLE — reference genuinely hard to find online
3. Agents disagree — needs manual review, one agent may have found something the other missed

Step 9: Mention output files

Tell the user:

Excel: <paper>_REFS.xlsx — detailed table with all fields + both verification rounds + final status RIS: <paper>_REFS.ris — ready to import into Zotero: File → Import → select the .ris file

Excel Table Columns

Why Double Control?

Single-agent verification can miss issues or produce false positives. Two independent rounds:

• Catch errors one agent missed
• Confirm real issues (both agents flag the same problem)
• Identify ambiguous cases (agents disagree → manual review)

Example Session

User: "verify references in my paper"

1. Identify the .docx file
2. Run py ref_verify.py "paper.docx" → 74 refs → JSON + RIS + Excel
3. Read JSON → 8 batches of 10
4. Round 1: Spawn batches 1-3 in parallel, then 4-6, then 7-8
5. Collect Round 1 results → save _AGENT1_FINDINGS.json → update Excel (agent 1)
6. Round 2: Spawn batches 1-3 in parallel (different prompt), then 4-6, then 7-8
7. Collect Round 2 results → save _AGENT2_FINDINGS.json → update Excel (agent 2)
8. Excel now has Final Status computed
9. Show double-control summary: "8 issues found, both agents agreed on 6, 2 need review"
10. Mention Excel + RIS files