paper-flow

name	paper-flow
description	Research paper citation tree workflow. Use when user wants to create citation trees, paper flow diagrams, or visualize research field development using academic APIs.

Paper Flow

Generate citation tree visualizations and Obsidian vault structure from academic paper research.

When to Use This Skill

Use when user wants to:

• "Research paper flow for [field/topic]"
• "Create citation tree for [paper]"
• "Visualize development flow of [research area]"
• "Generate paper flow diagram"
• "Build citation network visualization"

When NOT to Use This Skill

• General paper management tasks (use Zotero, Mendeley, etc.)
• Simple citation tracking without visualization
• Non-academic graph visualization tasks
• Quick single-paper lookups without analysis

Workflow

Phase 1: Paper Discovery

Trigger: User provides research field name or seed paper title/DOI/ID

Actions:

1. Query Semantic Scholar API for papers matching search criteria
2. Query arXiv API for additional metadata (if needed)
3. Extract paper metadata: title, authors, year, venue, citation count
4. Return list of candidate papers

MCP Tools Used:

• search_papers(query, limit=20, filters) - Semantic Scholar + arXiv
• get_paper_details(paper_id) - Full metadata extraction

Phase 2: Citation Network Extraction

Trigger: Papers identified from Phase 1

Actions:

1. For each paper, get forward citations (who cited this paper)
2. For each paper, get backward references (what this paper cites)
3. Build bidirectional citation graph
4. Analyze citation relationships to identify influence flow

MCP Tools Used:

• get_citations(paper_id, limit) - Forward citations
• get_references(paper_id, limit) - Backward references

Phase 3: Tree Structure Analysis

Trigger: Citation network built from Phase 2

Actions:

1. Identify root paper (highest citation count or most recent influential paper)
2. Determine parent-child relationships based on citation direction
3. Apply tree layout algorithm (Reingold-Tilford for clean trees)
4. Calculate node positions (x, y coordinates)
5. Assign hierarchy levels (depth, influence metrics)

Decision Rules:

Condition	Action
Root paper identified by user input	Use as explicit root
Multiple candidate roots (high citation count)	Select paper with highest influence metric
Disconnected components	Create separate trees, ask user to choose primary
Cyclic citations detected	Break cycles, use earliest dated paper as parent

Phase 4: Visual File Generation

Trigger: Tree structure with node positions calculated

Actions:

1. Generate Excalidraw JSON file:

   • Create text elements for paper titles
   • Add link property to each element (arXiv/DOI URL)
   • Create arrow elements between parent and child nodes
   • Export to [topic]-flow.excalidraw

2. Generate Obsidian Canvas JSON file:

   • Create file nodes (link to papers/{paperId}.md)
   • Create text nodes for labels/groups
   • Create edges between nodes
   • Export to [topic]-flow.canvas

Phase 5: Obsidian Note Generation

Trigger: Visual files generated

Actions:

1. For each paper, create markdown note:

   # {title}
   
   **Authors**: {authors}
   **Year**: {year}
   **Venue**: {venue}
   **Citation Count**: {count}
   
   ## Abstract
   {abstract}
   
   ## Link
   [Open on arXiv]({url})
   

2. Save to papers/{paperId}.md
3. Create index note linking all papers

Output Files

The workflow produces:

1. Excalidraw File: [topic]-flow.excalidraw

   • Hand-drawn style citation tree
   • Text nodes with paper titles + clickable links
   • Arrow elements showing citation relationships

2. Obsidian Canvas File: [topic]-flow.canvas

   • File nodes linked to markdown notes
   • Text nodes for labels/groups
   • Edge connections between nodes

3. Markdown Notes: papers/*.md

   • Detailed paper metadata
   • Abstracts, authors, venues
   • Links to source papers

Error Handling

Error Type	Recovery
Semantic Scholar rate limit exceeded	Add delay, notify user of remaining quota
Paper ID not found	Suggest alternative search terms, check DOI format
No citations found	Display warning, create single-node tree
API connection timeout	Retry with exponential backoff (up to 3 attempts)
Tree layout fails	Fall back to simple hierarchical layout

Examples

Example 1: Field Research

Input: "Research paper flow for attention mechanisms"

Workflow:

1. Search papers for "attention mechanisms" → 20 papers
2. Extract citations for key papers → 45+ papers
3. Build tree rooted at "Attention is All You Need"
4. Generate attention-flow.excalidraw and attention-flow.canvas
5. Create markdown notes in papers/ directory

Output:

• attention-flow.excalidraw (visual tree)
• attention-flow.canvas (Obsidian canvas)
• papers/*.md (paper notes)

Example 2: Seed Paper Expansion

Input: "Create citation tree for 10.1038/nature14539"

Workflow:

1. Get paper details via API
2. Get forward and backward citations
3. Build tree structure (cited-by = descendants)
4. Generate attention-flow.excalidraw
5. Generate attention-flow.canvas
6. Create paper notes

Output:

• attention-flow.excalidraw (visual tree)
• attention-flow.canvas (Obsidian canvas)
• papers/*.md (paper notes)

Example 3: Multi-Tree Comparison

Input: "Compare development flows for CNNs and RNNs"

Workflow:

1. Search papers for "CNN" → 15 papers
2. Search papers for "RNN" → 15 papers
3. Build separate trees for each field
4. Generate two side-by-side canvas files
5. Create comparison note linking both trees

Output:

• cnn-flow.excalidraw and cnn-flow.canvas
• rnn-flow.excalidraw and rnn-flow.canvas
• comparison-note.md linking both trees

Technical References

MCP Server Tools

• search_papers(): Semantic Scholar + arXiv paper search
• get_citations(): Forward citation extraction
• get_references(): Backward reference extraction
• get_paper_details(): Full metadata retrieval

File Generation Libraries

• Excalidraw-Interface: .excalidraw file generation
• PyJSONCanvas: .canvas file generation
• Markdown: Paper note templates

Layout Algorithms

• Reingold-Tilford: O(n) tree layout (preferred)
• NetworkX layouts: Alternative layouts for complex graphs
• Tidy tree algorithm: Parent-centered, minimal crossing

Quality Gates

Phase Completion Checklist

• Phase 1: 5-20 relevant papers found
• Phase 2: Citation network extracted (bidirectional)
• Phase 3: Tree structure determined, positions calculated
• Phase 4: Excalidraw and Canvas files generated
• Phase 5: All paper markdown notes created

Verification Steps

1. Excalidraw Verification:

   • Open [topic]-flow.excalidraw in Excalidraw
   • Verify all nodes render correctly
   • Verify text links are clickable
   • Verify arrows connect correct nodes

2. Obsidian Verification:

   • Open [topic]-flow.canvas in Obsidian
   • Verify all file nodes link to existing .md files
   • Verify graph view shows connections
   • Verify clicking nodes opens paper notes

3. Content Verification:

   • Spot-check 3 random paper notes for accuracy
   • Verify citations match source data
   • Verify abstracts are complete

Notes

Rate Limiting Awareness

• Semantic Scholar: 100 requests/5 minutes (free tier), higher with API key
• arXiv: 1 request/3 seconds (strict limit)
• Implement request queueing and delays as needed

Tree Layout Considerations

• Variable-length paper titles require dynamic node sizing
• Deep trees (>5 levels) may benefit from horizontal layout
• Consider citation count as node size indicator (larger = more influential)

Obsidian Integration Best Practices

• Use papers/ subdirectory for organization
• Include YAML frontmatter in notes for better Obsidian search
• Create index.md with all paper links for easy navigation
• Use Obsidian's graph view to discover unexpected connections