ref-verify

name: ref-verify description: | Verify all references in an academic paper (.docx) for accuracy via web search. Spawns TWO rounds of Sonnet sub-agents (double control) to independently verify each reference against online sources. Produces a detailed Excel table, a Zotero-compatible RIS file, and a summary of issues found.

TRIGGERS: "verify references", "check references accuracy", "תוודא הפניות", "בדוק הפניות", "reference verification", "are the references correct", "verify all refs", "export to zotero", "ris file", "zotero export"

Reference Verification Skill (Double Control)

Verify every reference in an academic paper for factual accuracy using two independent rounds of web search sub-agents (double control). Produces:

• Excel table with all parsed APA fields + verification status from both agents
• RIS file for Zotero/Mendeley/EndNote import
• Summary table of issues found

Architecture: Python extraction → JSON + RIS + Excel → Sonnet sub-agents (Round 1) → update Excel → Sonnet sub-agents (Round 2) → update Excel → final summary

How to Run — Follow These Steps Exactly

Step 1: Get the file path

Ask the user for the .docx file path if not provided. Look in the current working directory for .docx files if needed.

Step 2: Run the extraction script

py "C:/Users/user/.claude/skills/ref-verify/ref_verify.py" "<DOCX_PATH>"

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