validate-paper-links

name	validate_paper_links
description	Validate paper note links against actual paper references and influence

✅ Validate Paper Links Skill

Validate all [[Paper Title]] links in a paper note against the actual paper's references and citation patterns.

Goal: Prevent:

1. Links to papers NOT referenced in the current paper (hallucination)
2. Links to papers with incorrect titles or formatting
3. Links to low-influence papers (cited once, not foundational)
4. Broken file names (: not exchanged to -)

---

CRITICAL RULES

A link should exist only if:

1. ✅ The paper IS referenced in the current paper's bibliography/references
2. ✅ The paper is INFLUENTIAL (cited ≥2 times OR explicitly foundational/cited in intro/abstract)
3. ✅ Title is in exact Title Case matching the reference
4. ✅ File name properly formats : as - (e.g., Attention - Is All You Need)

A link should be removed if:

• ❌ Paper is NOT in the current paper's references
• ❌ Paper is cited only once in methods/results (low influence)
• ❌ Title formatting is incorrect
• ❌ File name violates naming convention

---

WORKFLOW

0. Read last-run timestamp

Read .claude/vault_maintanance.md and note the validate_paper_links: timestamp.

Default: incremental scan — only validate papers in Reading/ modified after the validate_paper_links: timestamp. Use find Reading/ -newer <reference_file> to identify changed paper notes. To use a reference file: touch -t YYYYMMDDHHMI /tmp/validate_ref && find Reading/ -newer /tmp/validate_ref

• If no papers were modified: skip and report "All paper links already validated."
• Only run a full rescan if the user explicitly requests it or no timestamp exists yet.

1. Get paper and note details

Read the paper note and extract:

• Paper URL: From frontmatter (arXiv HTML URL preferred)
• Paper title: From frontmatter or file name
• Authors: From frontmatter (if available)
• Year: From frontmatter (if available)

2. Fetch references section from arXiv HTML

Access paper:

• Use paper URL from frontmatter (typically https://arxiv.org/html/[paper-id]v[version])
• Use WebFetch with prompt focused only on references section
• Skip all paper content (abstract, introduction, methods, results, etc.)
• Extract only the bibliography/references section

Extract citation data:

• Parse reference list to get: titles, authors, years
• Build structured reference list from bibliography section
• Reference section is clearly marked on arXiv HTML pages

WebFetch optimization:

• Prompt: "Extract ONLY the bibliography/references section. Ignore all other paper content (abstract, introduction, methods, results). Return reference titles, authors, and years."
• This signals to skip 90% of paper content and focus only on references
• Saves tokens by not parsing paper text

Why arXiv HTML:

• ✅ Direct access to paper bibliography
• ✅ Pre-formatted references (easy to extract)
• ✅ No API rate limiting or authentication
• ✅ Reliable and consistent structure across papers
• ✅ No JavaScript rendering issues
• ✅ Can optimize WebFetch to skip content (token savings)

3. Read paper note

• Open paper note from Reading/[filename].md
• Extract all [[Paper Title]] links from "🔗 Connections to Other Work" section
• Build link list with current formatting

4. Validate each link

For each [[Paper Title]] in the note:

Check 1: Reference exists?

• Does this paper appear in the current paper's bibliography?
• If NO → FLAG: "Not referenced in paper" (candidate for removal)
• If YES → PASS

Check 2: Influence level

• Count how many times the paper is cited in the current paper's text
• Referenced paper with ≥2 citations in this paper = influential ✓
• Referenced paper cited once but foundational (cited in abstract/intro)? = influential ✓
• Referenced paper cited only once in methods/results (low-impact section)? = LOW influence (candidate for removal)
• If influence is borderline → ask user for judgment

Check 3: Title formatting

• Compare link title against reference list title
• Is it Title Case?
• Are colons : present in reference but - in link?
• Are special characters consistent?
• If mismatch → FLAG: "Title mismatch" or "Formatting error"

Check 4: File name validity

• Expected file name: exact title with : → -
• Is current link pointing to correct file name?
• Example: [[Attention - Is All You Need]] should match file Attention - Is All You Need.md
• If mismatch → FLAG: "File name doesn't match link"

5. Generate validation report

Group findings by severity:

🔴 CRITICAL (remove immediately):

• Papers not in references
• Papers cited only once in low-importance sections

🟡 NEEDS FIXING:

• Title case errors
• File name formatting errors (: not converted to -)

🟢 OK:

• Papers properly referenced
• Properly formatted
• Appropriately influential

❓ NEEDS USER JUDGMENT:

• Papers cited ~2 times (borderline influence)
• Foundational papers cited rarely but in key sections

6. Apply fixes

With user approval:

• Remove links: Delete [[Paper Title]] lines from "🔗 Connections to Other Work"
• Fix titles: Correct Title Case and formatting to match references
• Fix file names: Ensure : → - conversion
• Update note: Save corrected paper note
• Verify: Re-scan to confirm all links now valid

7. Update vault_maintanance.md

After completing validation (regardless of whether fixes were applied):

• Run date via Bash to get the current system time
• Read .claude/vault_maintanance.md
• Update validate_paper_links: line to current date and time in format DD-MM-YYYY HH:MM
• Reset papers_since_validate_links: to 0
• Write the updated file

Example update:

validate_paper_links: 10-02-2026 14:35

---

TOKEN EFFICIENCY

Optimizations:

• arXiv HTML for direct bibliography access (single WebFetch call)
• References-only extraction via targeted WebFetch prompt
• Skip all paper content (abstract, intro, methods, results)
• Bibliography section clearly marked and easy to extract
• No API calls, no rate limiting, no authentication needed
• Direct title + author list from bibliography
• Build simple title→reference mapping

Why this is efficient:

• 1 WebFetch call to arXiv HTML (direct paper access via frontmatter URL)
• Targeted prompt skips 90% of paper content (saves major tokens)
• Bibliography section is well-formatted and clearly delimited
• No API dependencies or rate limiting concerns
• Minimal parsing needed (just extract reference titles)
• No ambiguity in reference data

Workflow:

1. Read paper note frontmatter for arXiv HTML URL
2. WebFetch the arXiv HTML page with prompt: "Extract ONLY bibliography/references section. Skip all other content."
3. Extract bibliography/references section
4. Build reference list from bibliography
5. Validate links against reference list

Avoid:

• Semantic Scholar (JavaScript rendering, rate limiting issues)
• PDF parsing
• Regex patterns for extraction (bibliography is already structured)
• Processing full paper text (use targeted prompt instead)

Expected cost: ~100-150 tokens per paper (1 optimized WebFetch call + validation)

---

OUTPUT RULES

• Grouped by severity (CRITICAL → needs fixing → OK)
• File name / Link text / Issue / Suggested fix
• No prose, bullets only
• Example:

🔴 CRITICAL (remove):
- [[Paper Not In References]] - Not in bibliography → REMOVE

🟡 NEEDS FIXING:
- [[attention is all you need]] - Title case error → Fix to [[Attention Is All You Need]]
- [[My Paper: A Study]] - File name formatting → Should be [[My Paper - A Study]]

🟢 OK (keep):
- [[Transformers are All You Need]] ✓

---

SELF-CHECK

✅ Did I fetch the arXiv HTML page from the frontmatter URL? ✅ Did I extract all references from the bibliography section? ✅ Did I extract reference metadata (title, authors, year)? ✅ Did I check each link against the bibliography references? ✅ Did I assess influence (citation count/context in paper)? ✅ Did I validate Title Case formatting against bibliography titles? ✅ Did I check file name convention (: → -)? ✅ Did I group findings by severity? ✅ Did I get user approval before removing links? ✅ Did I verify all remaining links are valid? ✅ Did I update vault_maintanance.md with current timestamp?