academic-paper

Academic Paper Skill

Generate publication-ready academic research papers as professionally formatted PDFs. This skill covers the full pipeline: gathering inputs → writing/rewriting → figure creation → PDF formatting with reportlab → submission preparation for SSRN/arXiv.

Workflow Decision Tree

When the user triggers this skill, figure out where they are:

User has...             → Start at...
─────────────────────────────────────────────
A topic/idea only       → Stage 1 (Gather) → full pipeline
Bullet points/notes     → Stage 2 (Structure) → write → format
A markdown/text draft   → Stage 3 (Write/Rewrite) → format
A finished draft        → Stage 5 (Format as PDF)
A PDF, needs submission → Stage 6 (Submission Prep)

Always ask what they have and what they need. Don't assume full pipeline.

Stage 1: Gather Inputs

Collect these before ANY writing:

Required:

• Author full name, email, affiliation (company name or "Independent Researcher" — both valid)
• Paper type: preprint, position paper, empirical study, literature synthesis, technical report
• Existing content: draft file, notes, or topic description
• Target venue: SSRN, arXiv, specific journal, or general

Ask about:

• Do they have citations/references already, or do we need to find them?
• Do they have figures/diagrams, or should we create them?
• Any page limits or formatting constraints from the venue?
• Any specific sections they want or don't want?

If user provides a markdown/text draft:

1. Read the entire draft before doing anything
2. Count all citations — you'll need to verify none get lost during rewriting
3. Map the section structure
4. Identify: What's the thesis? What evidence supports it? What's missing?

Stage 2: Structure

Standard Paper Architecture

Title + Abstract (≤300 words) + Keywords (8-12)
1. Introduction         → Hook → Gap → Thesis → Contribution list
2. Background/Related   → Only what the reader needs; argue, don't survey
3-5. Core sections      → The actual contribution (varies by paper type)
6. Discussion           → Implications, limitations, future work
7. Conclusion           → Mirror intro, restate contributions concretely
References              → Hanging indent, consistent format
Appendices (optional)   → Supporting tables, proofs, supplementary data

Before Writing, Map the Argument

Do this explicitly — it prevents structural drift:

• Thesis: One sentence. The paper's central claim.
• Evidence chain: What supports it? Arrange in logical order.
• Counterarguments: What would a skeptic say? Plan where to address.
• Novel contribution: What is genuinely NEW here?
• Reader: Who is reading this, and what do they already know?

Stage 3: Write or Rewrite

Writing Principles

1. Enter the reader's world first. Open with what the audience already knows and cares about — a concrete scenario, a surprising finding, a known problem. Then introduce your contribution. Never lead with your own framework.

2. Every section ARGUES, not just DESCRIBES. Bad section heading: "Related Work." Good: "Three Independently Studied Phenomena That Interact as a System." Each section should advance a claim, not just organize information.

3. Concrete before abstract. Give a specific example or scenario, then generalize. The reader should visualize before you name.

4. Every data point gets a "so what" sentence. Never drop a statistic bare. After every cited finding, one sentence interpreting what it means for YOUR argument. Example: "Retrieval drops to 29.8% at 32K tokens (Modarressi et al., 2025). A user asking 'remember what I said about feeling worthless?' is making exactly this kind of semantic retrieval request — and the model is likely to fail."

5. Transitions advance the argument. Kill "Additionally", "Furthermore", "Moreover" as paragraph openers. Each transition should show logical progression: "This creates a problem that..." / "That finding has a direct corollary..." / "The mechanism just described operates differently when..."

6. Introduction and conclusion bookend. Open with a scenario → return to it in the conclusion with resolution.

7. Write for the skeptical expert. Smart, busy, looking for reasons to stop reading. Front-load importance. Cut ruthlessly.

Rewriting an Existing Draft — THE RULES

These are non-negotiable when polishing someone's draft:

1. Preserve ALL citations verbatim. Never change, remove, or invent citations. After

rewriting, diff-check: count refs in original vs. output. Must match.

1. Preserve ALL data points exactly. Numbers, percentages, dates — untouched.
2. Preserve the author's core argument. Improve the vehicle, don't change the destination.
3. Convert bullet/numbered lists to flowing prose in the body. Lists only in appendices.
4. Strengthen the opening — add a narrative hook if missing.
5. Add interpretive "so what" sentences after key findings.
6. Sharpen transitions between paragraphs and sections.
7. Trim redundancy. If two sentences say the same thing, keep the stronger one.
8. Check for orphan claims — assertions without supporting evidence or citations.

Stage 4: Figures

Creating SVG Diagrams

For flowcharts, system diagrams, conceptual figures — build them as SVG:

<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 680 950"
     width="680" height="950" font-family="Georgia, 'Times New Roman', serif">
  <defs>
    <marker id="arrow" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
      <polygon points="0 0, 10 3.5, 0 7" fill="#333"/>
    </marker>
    <filter id="shadow" x="-2%" y="-2%" width="104%" height="104%">
      <feDropShadow dx="1" dy="1" stdDeviation="2" flood-opacity="0.08"/>
    </filter>
  </defs>

  <!-- ALWAYS include a white background rect -->
  <rect width="680" height="950" fill="white"/>

  <!-- Then your diagram elements... -->
</svg>

Visual design rules:

• ALWAYS set explicit white background — SVGs default to transparent which renders as BLACK in PDFs
• Muted professional palette:
• Pink endpoints/warnings: fill="#ffcdd2" stroke="#e57373"
• Blue processes: fill="#c5cae9" stroke="#7986cb"
• Green outcomes: fill="#c8e6c9" stroke="#66bb6a"
• Neutral steps: fill="#fafafa" stroke="#aaa" or fill="#fff" stroke="#999"
• Subtle drop shadows via SVG <filter> (not CSS)
• Arrow markers (<marker>) for flow direction
• Dashed strokes (stroke-dasharray="8,5") for feedback loops
• Font: Georgia or Times New Roman, 11-13px
• Box labels: 3-6 words max. If longer, split across two <text> lines
• Rounded rects (rx="4") look more professional than sharp corners
• Add annotations for loop labels using rotated text

Converting SVG → high-res PNG for PDF embedding:

pip install cairosvg --break-system-packages -q

import cairosvg
cairosvg.svg2png(url='/home/claude/figure.svg', write_to='/home/claude/figure.png', scale=3)

Always 3× scale. This produces a crisp image even at print resolution.

Handling User-Provided Images with Dark/Transparent Backgrounds

This is a common gotcha — transparent PNGs render with BLACK backgrounds in PDFs.

Safe approach — replace only exact-black pixels (preserves dark text):

from PIL import Image
import numpy as np

img = Image.open('figure.png')
arr = np.array(img).copy()
mask = (arr[:,:,0] <= 2) & (arr[:,:,1] <= 2) & (arr[:,:,2] <= 2)
arr[mask] = [255, 255, 255]
Image.fromarray(arr).save('figure_white.png')

NEVER use:

• Flood-fill with high thresholds (destroys anti-aliased text)
• Blanket replacement of all dark pixels (destroys text strokes)
• Image.convert('RGBA') + alpha compositing if the image is already RGB with no alpha channel

The threshold ≤ 2 works because flat backgrounds use exact (0,0,0) or (1,1,1), while text anti-aliasing uses slightly higher values (3-30+).

Stage 5: For