kthorn/research-superpower/traversing-citations

Traversing Citation Networks

Overview

Intelligently follow citations backward (references) and forward (citing papers) using Semantic Scholar API.

Core principle: Only follow citations relevant to user's query. Avoid exponential explosion by filtering before traversing.

When to Use

Use this skill when:

• Found a highly relevant paper (score ≥ 7)
• Need to find related work
• User asks "what papers cite this?"
• Building comprehensive understanding of a topic

When NOT to use:

• Paper scored < 7 (not relevant enough to follow)
• Already at 50 papers (check with user first)
• Citations look off-topic from abstract

Citation Traversal Strategy

1. Get Paper ID from Semantic Scholar

Lookup by DOI:

curl "https://api.semanticscholar.org/graph/v1/paper/DOI:10.1234/example.2023?fields=paperId,title,year"

Response:

{
  "paperId": "abc123def456",
  "title": "Paper Title",
  "year": 2023
}

Save paperId - needed for citations/references queries

2. Backward Traversal (References)

Get references from paper:

curl "https://api.semanticscholar.org/graph/v1/paper/abc123def456/references?fields=contexts,intents,title,year,abstract,externalIds&limit=100"

Response format:

{
  "data": [
    {
      "citedPaper": {
        "paperId": "xyz789",
        "title": "Referenced Paper Title",
        "year": 2020,
        "abstract": "...",
        "externalIds": {
          "DOI": "10.5678/referenced.2020",
          "PubMed": "87654321"
        }
      },
      "contexts": [
        "...as described in previous work [15]...",
        "...we used the method from [15] to..."
      ],
      "intents": ["methodology", "background"]
    }
  ]
}

Filter for relevance:

For each reference, check:

1. Context keywords: Do citation contexts mention user's query terms?

• Example: If user asks about "IC50 values", look for contexts mentioning "IC50", "activity", "potency"

1. Title match: Does title contain relevant keywords?
2. Intent: Is intent "methodology" or "result" (more relevant) vs "background" (less relevant)?

Scoring:

• Context keywords match: +3 points
• Title keywords match: +2 points
• Intent is methodology/result: +2 points
• Recent (< 5 years old): +1 point

Only add to queue if score ≥ 5

3. Forward Traversal (Citations)

Get papers citing this one:

curl "https://api.semanticscholar.org/graph/v1/paper/abc123def456/citations?fields=title,year,abstract,externalIds&limit=100"

Response format:

{
  "data": [
    {
      "citingPaper": {
        "paperId": "def456ghi",
        "title": "Newer Paper Citing This",
        "year": 2024,
        "abstract": "We extended the work of [original paper]...",
        "externalIds": {
          "DOI": "10.9012/citing.2024"
        }
      }
    }
  ]
}

Filter for relevance:

For each citing paper:

1. Title match: Keywords present in title?
2. Abstract match: User's query terms in abstract?
3. Recency: Newer papers often build on findings (prioritize < 2 years)
4. Citation count: If Semantic Scholar provides, highly cited papers more likely relevant

Scoring:

• Title keywords match: +3 points
• Abstract keywords match: +2 points
• Recent (< 2 years): +2 points
• Moderate recency (2-5 years): +1 point

Only add to queue if score ≥ 5

4. Deduplication

Before adding to queue:

Check papers-reviewed.json:

doi = paper["externalIds"].get("DOI")
if doi in papers_reviewed:
    skip  # Already processed
else:
    add to queue

CRITICAL: After evaluating any paper from citation traversal, add it to papers-reviewed.json regardless of score. This prevents re-processing the same paper from multiple sources.

Track citation relationship in citations/citation-graph.json:

{
  "10.1234/example.2023": {
    "references": ["10.5678/ref1.2020", "10.5678/ref2.2021"],
    "cited_by": ["10.9012/cite1.2024", "10.9012/cite2.2024"]
  }
}

CRITICAL: Use ONLY citation-graph.json for citation tracking. Do NOT create custom files like forward_citation_pmids.txt or citation_analysis.md. All findings go in SUMMARY.md.

5. Process Queue

Add relevant citations to processing queue:

{
  "doi": "10.5678/referenced.2020",
  "title": "Referenced Paper",
  "relevance_score": 7,
  "source": "backward_from:10.1234/example.2023",
  "context": "Method citation - describes IC50 measurement protocol"
}

Then:

• Evaluate using evaluating-paper-relevance skill
• If relevant, extract data and potentially traverse its citations too

Smart Traversal Limits

To avoid explosion:

• Only traverse papers scoring ≥ 7 in initial evaluation
• Only follow citations scoring ≥ 5 in relevance filtering
• Limit traversal depth to 2 levels (original → references → references of references)
• Check with user after every 50 papers total

Breadth-first strategy:

1. Get all references + citations for current paper
2. Filter and score them
3. Add high-scoring ones to queue
4. Process next paper in queue
5. Repeat until queue empty or hit limit

Progress Reporting

Report as you traverse:

🔗 Analyzing citations for: "Original Paper Title"
   → Found 45 references, 12 look relevant
   → Found 23 citing papers, 8 look relevant
   → Adding 20 papers to queue
 
📄 [51/127] Following reference: "Method for measuring IC50"
   Source: Referenced by original paper in Methods section
   Abstract score: 7 → Fetching full text...

API Rate Limiting

Semantic Scholar limits:

• Free tier: 100 requests per 5 minutes
• With API key: 1000 requests per 5 minutes

Be efficient:

• Request multiple fields in one call (?fields=title,abstract,externalIds,year)
• Use limit=100 to get more results per request
• Cache responses - don't re-fetch same paper

If rate limited:

• Wait 5 minutes
• Report to user: "⏸️ Rate limited by Semantic Scholar API. Waiting 5 minutes..."
• Consider getting API key for higher limits

Integration with Other Skills

After traversing citations:

1. Queue now has N new papers to evaluate
2. For each, use evaluating-paper-relevance skill
3. If relevant, extract to SUMMARY.md
4. If highly relevant (≥9), traverse its citations too
5. Update citation-graph.json to track relationships

Quick Reference

Relevance Filtering Checklist

Before adding citation to queue:

• [ ] Check if already in papers-reviewed.json (skip if yes)
• [ ] Score based on context/title keywords (need ≥ 5)
• [ ] Verify external ID (DOI or PMID) exists
• [ ] Add source tracking ("backward_from:DOI" or "forward_from:DOI")
• [ ] Add to queue with metadata

Common Mistakes

Not tracking all evaluated papers: Only adding relevant papers to papers-reviewed.json → Add EVERY paper after evaluation to prevent re-review Creating custom analysis files: Making forward_citation_pmids.txt, CITATION_ANALYSIS.md, etc. → Use ONLY citation-graph.json and SUMMARY.md Following all citations: Exponential explosion → Filter before adding to queue Ignoring context: Citation might be tangential → Read context strings Not deduplicating: Re-process same papers → Always check papers-reviewed.json before and after evaluation Too deep: Following 5+ levels → Limit to 2 levels, check with user Missing forward citations: Only checking references → Use both backward and forward No rate limiting awareness: API blocks you → Add delays, handle 429 errors

Example Workflow

1. User asks: "Find selectivity data for BTK inhibitors"
2. Search finds Paper A (score: 9, has great IC50 data)
3. Traverse citations for Paper A:
   - References: 45 total, 12 relevant (mention "selectivity", "IC50")
   - Citations: 23 total, 8 relevant (newer papers on BTK)
4. Add 20 papers to queue
5. Evaluate first queued paper (score: 8)
6. Extract data, traverse its citations (add 5 more)
7. Continue until queue empty or user says stop

Next Steps

After traversing citations:

• Process queued papers with evaluating-paper-relevance
• Update SUMMARY.md with new findings
• Check if reached checkpoint (50 papers or 5 minutes)
• If checkpoint: ask user to continue or stop