Skill: wooonster/paper-reading (version 1.1.0)

--- name: paper-analyzer description: Deep-dive analysis of academic papers, with optional architecture diagrams of the paper's method. Use this skill whenever the user shares a research paper, a paste of paper content, a PDF attachment, or asks to analyze, summarize, critique, or explain a paper. Also trigger when the user passes --draw-structure, asks for a "paper architecture", or wants to visualize a method/pipeline from a paper. Trigger on phrases like "analyze this paper", "read this paper", "deep dive on", "explain the method", "draw this paper's architecture", "visualize this method". Don't wait for explicit skill invocation — if paper content is present, use it. --- # Paper Analyzer You are acting as a senior AI researcher and experienced peer reviewer. Your job is twofold: 1. Always produce a thorough, honest, actionable Markdown report file for the paper at the depth of a NeurIPS/ICML reviewer: rigorous, specific, and skeptical — but fair. 2. When asked (via `--draw-structure`, diagram intent, `--output`, or `--bg-theme`), also produce a publication-quality architecture diagram of the paper's method. Diagram output defaults to the report language, dark theme, and HTML unless the user requests otherwise. Before writing anything, read the full paper carefully. If it's a PDF, extract and read all sections including appendices. For arXiv links, fetch the HTML version via `web_fetch` (it's faster and richer than the PDF). Do not skim. ## Flags Parse these CLI-style flags from the user's message. Absent flags take defaults. Flag values are case-insensitive. | Flag | Values | Default | Effect | |---|---|---|---| | `--lang` | `en`, `cn` | `en` | Language for the written analysis. | | `--cn` | (presence) | — | Shorthand for `--lang cn`. | | `--draw-structure` | (presence) | off | In addition to the analysis, produce an architecture diagram of the paper's method. | | `--output` | `html`, `svg`, `png`, `all` | `html` | Diagram output format. Passing this flag implies drawing intent. `all` produces HTML + SVG + PNG. | | `--showcase-language` | `en`, `cn` | inherits `--lang` | Language for diagram labels. Defaults to the report language. Use this only to override the diagram language separately. | | `--bg-theme` | `dark`, `light` | `dark` | Visual background theme for the architecture diagram. `dark` uses the slate technical theme; `light` uses a paper-white canvas with darker text, softer fills, and light-theme strokes. | **Implicit `--draw-structure`:** if the user's message contains visual-intent keywords (*draw*, *diagram*, *architecture*, *visualize*, *showcase*, *structure*) alongside paper content, treat `--draw-structure` as set even without the flag. Also treat `--output`, `--bg-theme`, direct requests for "HTML/SVG/PNG diagram", or natural-language diagram theme requests like "light theme" / "dark theme" as drawing intent. **Language detection:** if the user writes to you in Chinese or says "用中文" / "中文输出", treat that as `--cn` for the Markdown report unless an explicit `--lang` overrides. The diagram language inherits the report language unless the user explicitly passes `--showcase-language`. ## Workflow 1. **Parse flags** from the user's message. 2. **Read the paper.** For PDFs, use `pdf-reading` tools. For arXiv URLs, `web_fetch` the `/html/` version. For pasted text, use it directly. 3. **Analyze and write the report.** Produce the 6-section structured analysis (below) and write it as a Markdown file. If `--lang cn`, load `references/output-cn.md` and use its structure instead. The Markdown report is mandatory whether or not a diagram is requested. 4. **Diagram (if drawing intent is present).** Load `references/diagram-design.md` for the design system, choose the palette from `--bg-theme`, then build per the *Diagram Output* section below. Defaults: `--showcase-language` inherits `--lang`, `--bg-theme dark`, `--output html`. 5. **Present outputs.** Return the Markdown report file path and any diagram file paths. Call `present_files` when available. ## File output behavior Always write the report to disk: - English report path: `/mnt/user-data/outputs/{paper_shortname}_report.md` - Non-English report path: `/mnt/user-data/outputs/{paper_shortname}_report_{lang}.md` If `/mnt/user-data/outputs/` is unavailable in the runtime, create `outputs/` in the current workspace and write the same filenames there. In the final response, briefly summarize what was produced and provide links/paths; do not paste the full report unless the user explicitly asks. ## Epistemic discipline **This is the most important rule: never state as fact something you cannot verify from the paper itself.** Tag every significant claim with one of: - `[paper]` — directly stated or shown in the paper - `[inferred]` — a reasonable inference not explicitly stated - `[external]` — relies on your background knowledge, not the paper If a key piece of information is absent from the paper (no ablation, no significance test, no compute budget), say so explicitly rather than working around it. The epistemic tags stay in English in all language modes — they are markers, not prose. --- # Analysis output structure Write all six sections below, in order, to the Markdown report under the default English mode. Do not skip sections. Do not merge them. For Chinese (`--lang cn`), replace this entire block with the structure in `references/output-cn.md`. ## Section 0 — Metadata Present as a compact table. One row per field. Do not editorialize here. | Field | Value | |---|---| | Title | | | Authors & affiliations | | | Venue / status | e.g. "NeurIPS 2024" or "arXiv preprint, not yet peer-reviewed" | | Code / data available | Yes / No / Partial — include URL if present | | Reproducibility signals | Note whether the paper reports: random seeds, confidence intervals, compute specs, dataset splits | Consult `references/venue-tiers.md` if you need to calibrate how much scrutiny to apply based on venue prestige. ## Section 1 — Problem and motivation Answer three questions, each in a short paragraph: 1. **What specific problem does this paper address?** Be precise. Avoid restating the abstract — reformulate in your own words, and where possible write the problem as a formal objective (e.g. "minimize X subject to Y"). 2. **Why do existing methods fail here?** Name the actual failure mode — quadratic complexity, distribution shift, label scarcity, optimization instability? Be specific about which prior methods fail and why. `[paper]` or `[inferred]` as appropriate. 3. **Why does this problem matter?** Connect to real downstream impact. If the paper makes this case poorly, say so. ## Section 2 — Technical method This is the core. Be precise and mathematical. **Core contribution** — one sentence. Format: "This paper proposes [X], which [mechanism], enabling [capability] that prior work could not achieve because [reason]." **Pipeline** — walk through the method end to end: - How is input represented / encoded? - What are the key architectural components or algorithmic steps? - What is the training objective? Write the loss: $\mathcal{L} = ...$ - Is there a gap between training and inference behavior? **What's actually new** — be specific about the logical delta from prior work. Don't say "they improve X" — explain what assumption prior work made that this paper abandons or modifies, and why that matters. **Complexity** — state time and space complexity for training and inference. `[paper]` if given, `[inferred]` if derived. ## Section 3 — Experimental evidence **Results table** — reproduce the key numbers from the main results table: | Dataset | Metric | Prior SOTA | This paper | Δ | |---|---|---|---|---| Mark all numbers `[paper]`. **Ablation findings** — identify which component drove most of the gain and which contributed little. If no ablation exists, flag this as a weakness. **Statistical rigor** — answer directly: - Are results reported with variance (std / confidence intervals)? - How many seeds / runs? - Is there a significance test? If none are reported, state this clearly. **Potential confounds** — look for weak baselines, favorable dataset selection, hyperparameter tuning asymmetry, or evaluation only on in-distribution data. ## Section 4 — Critical assessment Write as a skeptical but fair reviewer. Generic criticisms ("more experiments would help") are not useful. For each concern, state: - What the issue is - Whether it's `[paper]`-evident or `[inferred]` - Severity (critical / moderate / minor) Cover at least: - **Methodological concerns**: assumptions that may not hold, edge cases the method likely fails on, scalability limits - **Experimental concerns**: missing baselines, dataset gaps, cherry-picking risk - **Claim scope**: does the paper's framing overstate what the experiments actually show? - **Honest strengths**: also note what the paper does genuinely well ## Section 5 — Synthesis **TL;DR** — three sentences maximum. For a researcher who has 30 seconds. Cover: what the paper does, what the key result is, and the most important caveat. **Innovation classification** — pick one and justify briefly: - *Paradigm shift*: proposes a fundamentally new problem framing or solution class - *Method advance*: strong new mechanism within an established framework - *Engineering advance*: improves efficiency / scale without changing the core idea - *Application transfer*: applies a known method to a new domain effectively **Deployment readiness** — where does this method fit in practice today? What would need to change before using it in production? **Open problems** — list 2–3 specific research directions this paper leaves open. Concrete. "More experiments" is not an open problem. **Reproduction gotchas** — what are the most likely pain points for someone trying to reproduce this? (sensitivity to a specific hyperparameter, unlisted preprocessing, compute requirements) --- # Diagram output (when `--draw-structure`) Produce an architecture diagram that showcases the paper's method. Before building, load `references/diagram-design.md` for the complete design system (theme palettes, spacing, typography, layout rules). By default, diagram labels use the same language as the report, with dark theme and HTML output. Use `--bg-theme light` only when requested. Load `references/diagram-labels-cn.md` if `--showcase-language cn`. ## What the diagram must capture A good paper diagram answers three questions at a glance: 1. **What flows through the system?** The main pipeline: input → transformations → output. This is the backbone of the diagram, usually top-to-bottom or left-to-right. 2. **What is the paper's actual contribution?** Visually anchor it — make it larger, center it, use the emerald/core accent color. Include the key equations inline where they live in the flow. 3. **Why does it beat prior work?** A small contrast panel (only if the contrast is central to the paper's argument) showing the prior approach's failure mode vs. the new method's fix. This is the single most undervalued element — when included, it turns the diagram from a passive schematic into an argument. Supporting elements (include as space allows): legend, summary cards below the diagram, footer with paper citation. **Never** reproduce figures from the paper. Redraw the method in your own visual vocabulary. ## Choosing what to put in the diagram Not every paper needs every element. Calibrate by paper type: - **Method papers** (new loss, new architecture, new optimizer): emphasize the pipeline + contribution + contrast. This is GDPO-style. - **Systems papers**: emphasize component interactions, data flow, and deployment topology. Multiple services/modules each as their own box. - **Theoretical papers**: often not a good fit for this skill. If forced, show the proof structure or the key theorem's preconditions/conclusions. Mention in text when a diagram won't add value. - **Survey / taxonomy papers**: tree or DAG of categories rather than a linear pipeline. Color-code by category. If the paper does not have a clear method pipeline (e.g. pure benchmark paper, pure dataset release), tell the user a diagram may not add value — ask whether to proceed anyway. ## Output formats ### `--output html` (default) Produce a single self-contained `.html` file: - Embedded CSS with Google Fonts link (`JetBrains Mono` primary; add `Noto Sans SC` if `--showcase-language cn`) - Theme variables matching `--bg-theme`; do not just invert colors. Light diagrams need off-white page/canvas, dark readable text, restrained tinted fills, and subtle strokes/shadows. - Inline SVG diagram (typical viewBox: `1200 × 800–1200` depending on complexity) - Below the diagram: 3–6 summary cards capturing contributions, results, caveats (see `references/diagram-design.md` for the card pattern) - Footer with paper citation Path: `/mnt/user-data/outputs/{paper_shortname}_architecture.html` for dark, or `/mnt/user-data/outputs/{paper_shortname}_architecture_light.html` for light when both may be produced. Use the workspace `outputs/` fallback if `/mnt/user-data/outputs/` is unavailable. Use the starter at `assets/diagram-template.html` as a starting point. ### `--output svg` Produce a standalone `.svg` file. This is **different** from extracting the inline SVG — you must make it self-contained: - XML prolog: `<?xml version="1.0" encoding="UTF-8" standalone="no"?>` - SVG root with `xmlns="http://www.w3.org/2000/svg"` and explicit `width`/`height` - Embedded `<style>` element **wrapped in `<![CDATA[...]]>`** — this is required because `@import` URLs contain `&` which breaks XML parsing otherwise - Google Fonts `@import` with system-monospace fallback in `font-family` - Full-viewport background `<rect>` using the selected `--bg-theme` background (since there's no host HTML container) No cards, no HTML chrome. The SVG is the diagram alone. Path: `/mnt/user-data/outputs/{paper_shortname}_architecture.svg` for dark, or `/mnt/user-data/outputs/{paper_shortname}_architecture_light.svg` for light when both may be produced. Use the workspace `outputs/` fallback if `/mnt/user-data/outputs/` is unavailable. ### `--output png` 1. Produce the HTML first (full-page layout with cards). 2. Render via Playwright with `device_scale_factor=2` for retina quality. 3. Alternatively, render the standalone SVG alone if the user wants just the diagram without cards. Path: `/mnt/user-data/outputs/{paper_shortname}_architecture.png` for dark, or `/mnt/user-data/outputs/{paper_shortname}_architecture_light.png` for light when both may be produced. Use the workspace `outputs/` fallback if `/mnt/user-data/outputs/` is unavailable. Reference Playwright snippet: ```python from playwright.sync_api import sync_playwright with sync_playwright() as p: browser = p.chromium.launch() page = browser.new_page(viewport={"width": 1400, "height": 2000}, device_scale_factor=2) page.goto(f"file://{abs_path}") page.wait_for_load_state("networkidle") page.wait_for_timeout(1500) # let Google Fonts load page.screenshot(path=out_path, full_page=True) browser.close() ``` If Playwright is unavailable, fall back to headless Chromium (`chromium --headless --screenshot`) or `wkhtmltopdf`. Flag the fallback if used. ### `--output all` Produce HTML, SVG, and PNG together. Present all three via `present_files` with the HTML first (most interactive), then PNG, then SVG. ## Language handling for diagrams - `--showcase-language en`: English labels, `JetBrains Mono` font stack. - `--showcase-language cn`: Chinese labels. Add `Noto Sans SC` to the font stack: `font-family: 'JetBrains Mono', 'Noto Sans SC', 'Courier New', monospace;`. Translate section headers, box labels, captions. Keep standard technical terms in English (*Transformer*, *softmax*, *LoRA*, *attention*, etc.). Consult `references/diagram-labels-cn.md` for common translations. Note on mixed content: Chinese text in a monospace-primary stack sometimes looks uneven because Chinese glyphs are wider than Latin glyphs in the same font. This is expected — do not try to force equal widths. --- # Handling incomplete input If the user gives you only an abstract or title without full text: - Analyze what you can and still write the Markdown report file, but state upfront that you're working from limited information. - Do not invent technical details you can't verify. - Ask if they can share the full paper. - If `--draw-structure` was requested, explain that a method diagram needs the full method section; offer to produce a provisional diagram from the abstract only if the user insists. If the paper is very long (60+ pages), prioritize: abstract, introduction, method section, main results table, ablation, conclusion. Note if you did not read appendices. # Tone Write like a senior colleague reviewing a paper for a workshop, not like a press release. Use precise technical language. Don't hedge everything — take positions when the evidence supports them. If a paper is weak, say so clearly and specifically. If it's strong, say that too. # Reference files - `references/output-cn.md` — Chinese analysis output structure. Load when `--lang cn`. - `references/venue-tiers.md` — venue prestige calibration for Section 0. - `references/diagram-design.md` — full design system for architecture diagrams (colors, spacing, typography, arrows, component patterns). **Load before building any diagram.** - `references/diagram-labels-cn.md` — Chinese translations for common diagram labels. Load when `--showcase-language cn`. - `assets/diagram-template.html` — starter template for the HTML diagram.

path: assets/diagram-template.html
content: <!DOCTYPE html>
<html lang="en" data-theme="dark">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>[PAPER NAME] Architecture</title>
  <!-- For Chinese labels, add Noto+Sans+SC to the family parameter -->
  <link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
  <style>
    * { margin: 0; padding: 0; box-sizing: border-box; }

    /*
      Set data-theme="dark" or data-theme="light" on <html>.
      When generating standalone SVG, inline the resolved values instead.
    */
    :root,
    html[data-theme="dark"] {
      --page-bg: #020617;
      --panel-bg: rgba(15, 23, 42, 0.5);
      --panel-border: #1e293b;
      --svg-bg: #020617;
      --box-mask: #0f172a;
      --text-main: #ffffff;
      --text-muted: #94a3b8;
      --text-faint: #475569;
      --grid: #1e293b;
      --arrow: #64748b;
      --core-fill: rgba(6, 78, 59, 0.4);
      --core-stroke: #34d399;
      --data-fill: rgba(8, 51, 68, 0.4);
      --data-stroke: #22d3ee;
      --generic-fill: rgba(30, 41, 59, 0.5);
      --generic-stroke: #94a3b8;
      --warning-fill: rgba(136, 19, 55, 0.25);
      --warning-stroke: #fb7185;
      --reward-fill: rgba(251, 146, 60, 0.3);
      --reward-stroke: #fb923c;
      --priority-fill: rgba(76, 29, 149, 0.4);
      --priority-stroke: #a78bfa;
      --shadow: none;
    }

    html[data-theme="light"] {
      --page-bg: #f8fafc;
      --panel-bg: #ffffff;
      --panel-border: #d8e0ea;
      --svg-bg: #ffffff;
      --box-mask: #ffffff;
      --text-main: #0f172a;
      --text-muted: #475569;
      --text-faint: #64748b;
      --grid: #dbe4ee;
      --arrow: #94a3b8;
      --core-fill: rgba(16, 185, 129, 0.13);
      --core-stroke: #047857;
      --data-fill: rgba(14, 165, 233, 0.12);
      --data-stroke: #0284c7;
      --generic-fill: rgba(100, 116, 139, 0.10);
      --generic-stroke: #64748b;
      --warning-fill: rgba(244, 63, 94, 0.12);
      --warning-stroke: #e11d48;
      --reward-fill: rgba(249, 115, 22, 0.13);
      --reward-stroke: #ea580c;
      --priority-fill: rgba(139, 92, 246, 0.12);
      --priority-stroke: #7c3aed;
      --shadow: 0 12px 32px rgba(15, 23, 42, 0.08);
    }

    body {
      font-family: 'JetBrains Mono', monospace;
      background: var(--page-bg);
      min-height: 100vh;
      padding: 2rem;
      color: var(--text-main);
    }

    .container { max-width: 1280px; margin: 0 auto; }

    .header { margin-bottom: 2rem; }

    .header-row {
      display: flex; align-items: center; gap: 1rem;
      margin-bottom: 0.5rem;
    }

    .pulse-dot {
      width: 12px; height: 12px;
      background: var(--core-stroke);  /* emerald — matches the core contribution accent */
      border-radius: 50%;
      animation: pulse 2s infinite;
    }

    @keyframes pulse {
      0%, 100% { opacity: 1; }
      50% { opacity: 0.5; }
    }

    h1 { font-size: 1.5rem; font-weight: 700; letter-spacing: -0.025em; }

    .subtitle {
      color: var(--text-muted); font-size: 0.875rem; margin-left: 1.75rem;
    }

    .paper-ref {
      color: var(--text-faint); font-size: 0.75rem;
      margin-left: 1.75rem; margin-top: 0.25rem;
    }

    .diagram-container {
      background: var(--panel-bg);
      border-radius: 1rem;
      border: 1px solid var(--panel-border);
      padding: 1.5rem;
      overflow-x: auto;
      box-shadow: var(--shadow);
    }

    svg { width: 100%; min-width: 1100px; display: block; }

    .cards {
      display: grid;
      grid-template-columns: repeat(auto-fit, minmax(280px, 1fr));
      gap: 1rem;
      margin-top: 2rem;
    }

    .card {
      background: var(--panel-bg);
      border-radius: 0.75rem;
      border: 1px solid var(--panel-border);
      padding: 1.25rem;
      box-shadow: var(--shadow);
    }

    .card-header {
      display: flex; align-items: center; gap: 0.5rem;
      margin-bottom: 0.75rem;
    }

    .card-dot {
      width: 8px; height: 8px; border-radius: 50%;
    }

    .card-dot.cyan    { background: var(--data-stroke); }
    .card-dot.emerald { background: var(--core-stroke); }
    .card-dot.violet  { background: var(--priority-stroke); }
    .card-dot.amber   { background: #f59e0b; }
    .card-dot.rose    { background: var(--warning-stroke); }
    .card-dot.orange  { background: var(--reward-stroke); }

    .card h3 { font-size: 0.875rem; font-weight: 600; }

    .card ul {
      list-style: none;
      color: var(--text-muted);
      font-size: 0.75rem;
    }

    .card li {
      margin-bottom: 0.5rem;
      line-height: 1.5;
    }

    .footer {
      text-align: center;
      margin-top: 1.5rem;
      color: var(--text-faint);
      font-size: 0.75rem;
    }
  </style>
</head>
<body>
  <div class="container">
    <!-- ===== HEADER ===== -->
    <div class="header">
      <div class="header-row">
        <div class="pulse-dot"></div>
        <h1>[PAPER SHORT NAME] · [Full title fragment]</h1>
      </div>
      <p class="subtitle">[One-line method summary — what the paper does]</p>
      <p class="paper-ref">[Authors], [Affiliation] · arXiv:[ID] ([Month Year])</p>
    </div>

    <!-- ===== MAIN DIAGRAM ===== -->
    <div class="diagram-container">
      <!-- Set viewBox to match your content. 1200 × 800 is a typical starting point. -->
      <svg viewBox="0 0 1200 800" xmlns="http://www.w3.org/2000/svg">

        <!-- Marker and grid definitions -->
        <defs>
          <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
            <polygon points="0 0, 10 3.5, 0 7" fill="var(--arrow)"/>
          </marker>
          <marker id="arrowhead-emerald" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
            <polygon points="0 0, 10 3.5, 0 7" fill="var(--core-stroke)"/>
          </marker>
          <marker id="arrowhead-rose" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
            <polygon points="0 0, 10 3.5, 0 7" fill="var(--warning-stroke)"/>
          </marker>
          <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
            <path d="M 40 0 L 0 0 0 40" fill="none" stroke="var(--grid)" stroke-width="0.5"/>
          </pattern>
        </defs>

        <!-- ===================================================================
             SECTION 1 · MAIN PIPELINE
             Top-to-bottom or left-to-right flow of the method.
             =================================================================== -->

        <!-- Background and grid — always first -->
        <rect width="100%" height="100%" fill="var(--svg-bg)"/>
        <rect width="100%" height="100%" fill="url(#grid)"/>

        <text x="40" y="40" fill="var(--core-stroke)" font-size="11" font-weight="700"
              letter-spacing="1">▸ MAIN PIPELINE</text>

        <!-- Input component (cyan) -->
        <rect x="40" y="60" width="140" height="70" rx="6" fill="var(--box-mask)"/>
        <rect x="40" y="60" width="140" height="70" rx="6"
              fill="var(--data-fill)" stroke="var(--data-stroke)" stroke-width="1.5"/>
        <text x="110" y="88" fill="var(--text-main)" font-size="11"
              font-weight="600" text-anchor="middle">[Input]</text>
        <text x="110" y="106" fill="var(--text-muted)" font-size="9" text-anchor="middle">[sublabel]</text>

        <!-- Arrow -->
        <line x1="180" y1="95" x2="218" y2="95" stroke="var(--arrow)" stroke-width="1.5"
              marker-end="url(#arrowhead)"/>

        <!-- Core contribution (emerald — make this the visual anchor) -->
        <rect x="220" y="60" width="180" height="70" rx="6" fill="var(--box-mask)"/>
        <rect x="220" y="60" width="180" height="70" rx="6"
              fill="var(--core-fill)" stroke="var(--core-stroke)" stroke-width="1.5"/>
        <text x="310" y="88" fill="var(--text-main)" font-size="11"
              font-weight="600" text-anchor="middle">[Core method]</text>
        <text x="310" y="106" fill="var(--core-stroke)" font-size="9" text-anchor="middle">[key formula]</text>

        <!-- Arrow -->
        <line x1="400" y1="95" x2="438" y2="95" stroke="var(--arrow)" stroke-width="1.5"
              marker-end="url(#arrowhead)"/>

        <!-- Output component -->
        <rect x="440" y="60" width="140" height="70" rx="6" fill="var(--box-mask)"/>
        <rect x="440" y="60" width="140" height="70" rx="6"
              fill="var(--generic-fill)" stroke="var(--generic-stroke)" stroke-width="1.5"/>
        <text x="510" y="88" fill="var(--text-main)" font-size="11"
              font-weight="600" text-anchor="middle">[Output]</text>
        <text x="510" y="106" fill="var(--text-muted)" font-size="9" text-anchor="middle">[sublabel]</text>

        <!-- ===================================================================
             SECTION 2 · CONTRAST PANEL (optional — only if central to argument)
             Side-by-side: prior work (rose) vs this paper (emerald).
             =================================================================== -->

        <text x="40" y="200" fill="var(--warning-stroke)" font-size="11" font-weight="700"
              letter-spacing="1">⚠ KEY INSIGHT · [Why prior approach fails]</text>

        <!-- Prior work (rose — warning color) -->
        <rect x="40" y="220" width="540" height="140" rx="8" fill="var(--box-mask)"/>
        <rect x="40" y="220" width="540" height="140" rx="8"
              fill="var(--warning-fill)" stroke="var(--warning-stroke)" stroke-width="1.5"/>
        <text x="310" y="245" fill="var(--warning-stroke)" font-size="11"
              font-weight="700" text-anchor="middle">[Prior Method]</text>
        <text x="310" y="265" fill="var(--text-muted)" font-size="9"
              text-anchor="middle" font-style="italic">[prior approach formula]</text>
        <!-- Add concrete example numbers here -->
        <text x="60" y="295" fill="var(--text-main)" font-size="9" font-weight="600">[example setup]:</text>
        <text x="60" y="315" fill="var(--warning-stroke)" font-size="9">[result showing failure]</text>
        <text x="60" y="340" fill="var(--warning-stroke)" font-size="9"
              font-weight="700">✗ [Failure mode in one line]</text>

        <!-- VS divider -->
        <text x="610" y="295" fill="var(--text-muted)" font-size="14"
              font-weight="700" text-anchor="middle">→</text>

        <!-- This paper (emerald) -->
        <rect x="640" y="220" width="540" height="140" rx="8" fill="var(--box-mask)"/>
        <rect x="640" y="220" width="540" height="140" rx="8"
              fill="var(--core-fill)" stroke="var(--core-stroke)" stroke-width="1.5"/>
        <text x="910" y="245" fill="var(--core-stroke)" font-size="11"
              font-weight="700" text-anchor="middle">[This paper's method]</text>
        <text x="910" y="265" fill="var(--text-muted)" font-size="9"
              text-anchor="middle" font-style="italic">[new approach formula]</text>
        <!-- Same example under new method -->
        <text x="660" y="295" fill="var(--text-main)" font-size="9" font-weight="600">[same setup]:</text>
        <text x="660" y="315" fill="var(--core-stroke)" font-size="9">[result showing fix]</text>
        <text x="660" y="340" fill="var(--core-stroke)" font-size="9"
              font-weight="700">✓ [How it fixes things]</text>

        <!-- ===================================================================
             LEGEND — always OUTSIDE region boundaries
             =================================================================== -->

        <rect x="950" y="35" width="195" height="80" rx="6"
              fill="var(--panel-bg)" stroke="var(--panel-border)" stroke-width="1"/>
        <text x="960" y="50" fill="var(--text-main)" font-size="9" font-weight="700">LEGEND</text>

        <rect x="960" y="58" width="14" height="9" rx="2"
              fill="var(--data-fill)" stroke="var(--data-stroke)" stroke-width="1"/>
        <text x="980" y="66" fill="var(--text-muted)" font-size="8">Input / data</text>

        <rect x="960" y="72" width="14" height="9" rx="2"
              fill="var(--core-fill)" stroke="var(--core-stroke)" stroke-width="1"/>
        <text x="980" y="80" fill="var(--text-muted)" font-size="8">Core method</text>

        <rect x="960" y="86" width="14" height="9" rx="2"
              fill="var(--warning-fill)" stroke="var(--warning-stroke)" stroke-width="1"/>
        <text x="980" y="94" fill="var(--text-muted)" font-size="8">Prior work / failure</text>

        <rect x="960" y="100" width="14" height="9" rx="2"
              fill="var(--generic-fill)" stroke="var(--generic-stroke)" stroke-width="1"/>
        <text x="980" y="108" fill="var(--text-muted)" font-size="8">External / generic</text>

      </svg>
    </div>

    <!-- ===== SUMMARY CARDS (3–6 total; tune per paper) ===== -->
    <div class="cards">
      <div class="card">
        <div class="card-header">
          <div class="card-dot rose"></div>
          <h3>The Problem</h3>
        </div>
        <ul>
          <li>• [What failure mode the paper identifies]</li>
          <li>• [Why prior approaches miss it]</li>
          <li>• [Concrete example where it shows up]</li>
        </ul>
      </div>

      <div class="card">
        <div class="card-header">
          <div class="card-dot emerald"></div>
          <h3>The Fix</h3>
        </div>
        <ul>
          <li>• [Step 1 of the method]</li>
          <li>• [Step 2]</li>
          <li>• [Step 3 — what's genuinely new]</li>
        </ul>
      </div>

      <div class="card">
        <div class="card-header">
          <div class="card-dot amber"></div>
          <h3>Empirical Validation</h3>
        </div>
        <ul>
          <li>• [Headline number with dataset + metric]</li>
          <li>• [Second strongest result]</li>
          <li>• [Honest limitation in the numbers]</li>
        </ul>
      </div>
    </div>

    <!-- ===== FOOTER ===== -->
    <p class="footer">
      [Paper short name] · [Authors] · arXiv:[ID] ([Date]) · [Optional: code URL]
    </p>
  </div>
</body>
</html>


path: README.md
content: # Paper Analyzer

Paper Analyzer turns a paper link, PDF, or pasted paper text into a rigorous research report and, when requested, a method diagram.

By default, it reads the full paper and writes an English Markdown report. If the user asks for another language, the report and diagram labels inherit that language. If the user asks for a diagram, architecture view, HTML/SVG/PNG output, or a dark/light theme, it also generates a publication-style architecture diagram.

## What It Does

- Reads arXiv HTML, PDFs, attachments, or pasted paper content.
- Produces a structured Markdown report with metadata, motivation, method, evidence, critique, and synthesis.
- Tags substantive claims as `[paper]`, `[inferred]`, or `[external]`.
- Creates method diagrams in HTML, SVG, PNG, or all formats.
- Supports dark and light diagram themes.
- Supports English and Chinese report/diagram output.

## Default Behavior

Without diagram instructions, the skill still writes a report:

```text
Read this paper: https://arxiv.org/abs/2601.05242
```

Expected output:

- `outputs/{paper_shortname}_report.md`

## Diagram Behavior

Diagram output is triggered by visual intent or by diagram flags:

```text
Read this paper and draw the method architecture: https://arxiv.org/abs/2601.05242
```

Default diagram output:

- English labels unless the report language is changed
- Dark theme
- HTML format

## Useful Flags

| Flag | Example | Effect |
|---|---|---|
| `--lang cn` | `--lang cn` | Generate Chinese report and Chinese diagram labels by default. |
| `--cn` | `--cn` | Shorthand for Chinese output. |
| `--draw-structure` | `--draw-structure` | Generate a method diagram. |
| `--output` | `--output all` | Choose `html`, `svg`, `png`, or `all`; implies diagram generation. |
| `--bg-theme` | `--bg-theme light` | Choose `dark` or `light` diagram theme. |
| `--showcase-language` | `--showcase-language en` | Override diagram label language separately from the report. |

## Examples

English report only:

```text
Analyze https://arxiv.org/abs/2601.05242
```

Chinese report and Chinese dark HTML diagram:

```text
用中文读这篇论文并画架构图：https://arxiv.org/abs/2601.05242
```

English report with light SVG diagram:

```text
Read this paper and create a diagram --bg-theme light --output svg https://arxiv.org/abs/2601.05242
```

Chinese report with English diagram:

```text
中文报告，图用英文 --showcase-language en --draw-structure https://arxiv.org/abs/2601.05242
```

## Output Files

Primary report:

- `/mnt/user-data/outputs/{paper_shortname}_report.md`
- Falls back to workspace `outputs/` if `/mnt/user-data/outputs/` is unavailable.

Diagram files:

- `{paper_shortname}_architecture.html`
- `{paper_shortname}_architecture.svg`
- `{paper_shortname}_architecture.png`
- Light theme outputs may use `_light` suffix when both themes could be produced.

## ClawHub Introduction

**English:** Paper Analyzer is a research-paper deep reading skill for Codex. It reads papers from arXiv, PDFs, or pasted text, writes a rigorous Markdown review, and can generate polished method diagrams in dark or light themes.

**中文：** Paper Analyzer 是一个面向 Codex 的论文深度阅读 Skill。它可以读取 arXiv、PDF 或粘贴的论文内容，生成严谨的 Markdown 评审报告，并可绘制暗色或亮色主题的方法架构图。


path: README_zh.md
content: # Paper Analyzer（论文分析器）

Paper Analyzer 可以把论文链接、PDF 或粘贴的论文内容，转换成严谨的研究报告；在需要时，还能生成方法架构图。

默认情况下，它会完整阅读论文并写出英文 Markdown 报告。如果用户指定中文或其他语言，报告和图示标签会继承该语言。如果用户要求画图、架构图、HTML/SVG/PNG 输出，或指定暗色/亮色主题，它会额外生成出版级风格的方法图。

## 功能

- 读取 arXiv HTML、PDF、附件或粘贴的论文文本。
- 生成结构化 Markdown 报告，覆盖元信息、问题动机、技术方法、实验证据、批判性评估和综合结论。
- 对重要判断标注 `[paper]`、`[inferred]` 或 `[external]`，避免把推断说成事实。
- 生成 HTML、SVG、PNG 或全部格式的方法架构图。
- 支持暗色和亮色图示主题。
- 支持英文和中文报告/图示输出。

## 默认行为

没有画图指令时，仍然会写报告：

```text
Read this paper: https://arxiv.org/abs/2601.05242
```

预期输出：

- `outputs/{paper_shortname}_report.md`

## 画图行为

当用户表达视觉意图，或传入图示相关 flag 时，会触发制图：

```text
阅读这篇论文并画出方法架构图：https://arxiv.org/abs/2601.05242
```

默认图示输出：

- 图示语言继承报告语言
- 暗色主题
- HTML 格式

## 常用 Flags

| Flag | 示例 | 作用 |
|---|---|---|
| `--lang cn` | `--lang cn` | 生成中文报告，并默认生成中文图示标签。 |
| `--cn` | `--cn` | 中文输出的简写。 |
| `--draw-structure` | `--draw-structure` | 生成方法架构图。 |
| `--output` | `--output all` | 选择 `html`、`svg`、`png` 或 `all`；该 flag 会隐式触发制图。 |
| `--bg-theme` | `--bg-theme light` | 选择 `dark` 或 `light` 图示主题。 |
| `--showcase-language` | `--showcase-language en` | 单独覆盖图示语言，不影响报告语言。 |

## 示例

只生成英文报告：

```text
Analyze https://arxiv.org/abs/2601.05242
```

生成中文报告和中文暗色 HTML 图：

```text
用中文读这篇论文并画架构图：https://arxiv.org/abs/2601.05242
```

生成英文报告和亮色 SVG 图：

```text
Read this paper and create a diagram --bg-theme light --output svg https://arxiv.org/abs/2601.05242
```

中文报告，但图示使用英文：

```text
中文报告，图用英文 --showcase-language en --draw-structure https://arxiv.org/abs/2601.05242
```

## 输出文件

主报告：

- `/mnt/user-data/outputs/{paper_shortname}_report.md`
- 如果 `/mnt/user-data/outputs/` 不可用，则回退到当前 workspace 的 `outputs/` 目录。

图示文件：

- `{paper_shortname}_architecture.html`
- `{paper_shortname}_architecture.svg`
- `{paper_shortname}_architecture.png`
- 亮色主题在可能同时输出多主题时，可使用 `_light` 后缀。

## ClawHub 简介

**中文：** Paper Analyzer 是一个面向 Codex 的论文深度阅读 Skill。它可以读取 arXiv、PDF 或粘贴的论文内容，生成严谨的 Markdown 评审报告，并可绘制暗色或亮色主题的方法架构图。

**English:** Paper Analyzer is a research-paper deep reading skill for Codex. It reads papers from arXiv, PDFs, or pasted text, writes a rigorous Markdown review, and can generate polished method diagrams in dark or light themes.


path: references/diagram-design.md
content: # Diagram design system

Load this file before building any architecture diagram with `--draw-structure`. It defines every visual primitive you need: colors, typography, spacing, arrows, component patterns. Treat these as the defaults — only deviate with a reason.

## Theme selection

The `--bg-theme` flag controls the diagram palette:

- `--bg-theme dark` (default): technical slate canvas, luminous strokes, white component titles.
- `--bg-theme light`: paper-white canvas, darker text, softer tinted fills, and lower-contrast grid/strokes. Do **not** reuse dark fills on a light canvas; they become muddy and too heavy.

Implement themes with CSS variables in HTML where possible. For standalone SVG, inline the chosen literal colors.

## Canvas

- **Dark background:** `#020617` (slate-950).
- **Light background:** `#f8fafc` (slate-50) for the page, with `#ffffff` or `#f8fafc` for the SVG canvas.
- **Grid overlay:** subtle 40px grid for spatial reference. Use `#1e293b` at `0.5` stroke on dark; use `#dbe4ee` at `0.6` stroke on light.
  ```svg
  <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
    <path d="M 40 0 L 0 0 0 40" fill="none" stroke="GRID_COLOR" stroke-width="0.5"/>
  </pattern>
  <rect width="100%" height="100%" fill="url(#grid)"/>
  ```
- **ViewBox:** start with `1200 × 800`. Expand height as needed — don't cram content to fit.

## Color semantics

Every box's color tells the reader what *kind* of thing it is. Use these mappings consistently within a diagram.

### Dark theme palette

| Role in a paper diagram | Fill | Stroke | Hex stroke |
|---|---|---|---|
| **Core contribution / novel method** | `rgba(6, 78, 59, 0.4)` | emerald | `#34d399` |
| **Input / data / rollouts** | `rgba(8, 51, 68, 0.4)` | cyan | `#22d3ee` |
| **Storage / memory / dataset** | `rgba(76, 29, 149, 0.4)` | violet | `#a78bfa` |
| **External / baseline / generic** | `rgba(30, 41, 59, 0.5)` | slate | `#94a3b8` |
| **Prior work's failure / warning** | `rgba(136, 19, 55, 0.4)` | rose | `#fb7185` |
| **Reward / signal / intermediate flow** | `rgba(251, 146, 60, 0.3)` | orange | `#fb923c` |
| **Region / cluster boundary** | `rgba(251, 191, 36, 0.05)` | amber | `#fbbf24` |
| **Priority / weighting / auxiliary** | `rgba(76, 29, 149, 0.4)` | violet | `#a78bfa` |

Supporting dark tokens:

| Token | Value |
|---|---|
| `page-bg` | `#020617` |
| `panel-bg` | `rgba(15, 23, 42, 0.5)` |
| `box-mask` | `#0f172a` |
| `text-main` | `#ffffff` |
| `text-muted` | `#94a3b8` |
| `text-faint` | `#475569` |
| `grid` | `#1e293b` |
| `arrow` | `#64748b` |

### Light theme palette

Use the same semantic hues, but shift to deeper strokes and pale fills so the diagram reads cleanly on white.

| Role in a paper diagram | Fill | Stroke | Hex stroke |
|---|---|---|---|
| **Core contribution / novel method** | `rgba(16, 185, 129, 0.13)` | emerald | `#047857` |
| **Input / data / rollouts** | `rgba(14, 165, 233, 0.12)` | cyan/sky | `#0284c7` |
| **Storage / memory / dataset** | `rgba(124, 58, 237, 0.11)` | violet | `#7c3aed` |
| **External / baseline / generic** | `rgba(100, 116, 139, 0.10)` | slate | `#64748b` |
| **Prior work's failure / warning** | `rgba(244, 63, 94, 0.12)` | rose | `#e11d48` |
| **Reward / signal / intermediate flow** | `rgba(249, 115, 22, 0.13)` | orange | `#ea580c` |
| **Region / cluster boundary** | `rgba(16, 185, 129, 0.06)` | emerald | `#059669` |
| **Priority / weighting / auxiliary** | `rgba(139, 92, 246, 0.12)` | violet | `#7c3aed` |

Supporting light tokens:

| Token | Value |
|---|---|
| `page-bg` | `#f8fafc` |
| `panel-bg` | `#ffffff` |
| `box-mask` | `#ffffff` |
| `text-main` | `#0f172a` |
| `text-muted` | `#475569` |
| `text-faint` | `#64748b` |
| `grid` | `#dbe4ee` |
| `arrow` | `#94a3b8` |
| `panel-border` | `#d8e0ea` |

**The one rule to never break:** the paper's core contribution gets emerald. Everything else is context.

Light theme design notes:

- Prefer white panels over gray panels; use border and shadow for structure.
- Use deeper accent strokes (`#047857`, `#0284c7`, `#e11d48`) rather than neon colors.
- Text inside boxes should be `#0f172a`; sublabels should be `#475569`.
- Avoid large saturated backgrounds. Keep fills around 10–14% opacity.
- Use a soft shadow on the main diagram container only, not on every box.

## Typography

Primary font: **JetBrains Mono** (monospace gives the technical aesthetic; consistent character widths help grid-align elements).

```html
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap" rel="stylesheet">
```

For Chinese labels (`--showcase-language cn`), extend the stack:

```css
font-family: 'JetBrains Mono', 'Noto Sans SC', 'Courier New', monospace;
```

And include `Noto+Sans+SC` in the Google Fonts URL.

Size hierarchy:

| Purpose | Size | Weight | Color |
|---|---|---|---|
| Section headers (▸ GDPO PIPELINE) | 11 | 700 | accent (match section) |
| Component name (box title) | 11 | 600 | `text-main` |
| Component sublabel | 9 | 400 | `text-muted` |
| Small annotations / arrow labels | 8 | 400 | `text-muted` |
| Tiny legend labels | 8 | 400 | `text-muted` |
| Math / formulas inside boxes | 10–11 | italic | accent |

## Component patterns

### Standard component box

```svg
<rect x="X" y="Y" width="W" height="H" rx="6"
      fill="FILL_COLOR" stroke="STROKE_COLOR" stroke-width="1.5"/>
<text x="CENTER_X" y="Y+20" fill="TEXT_MAIN" font-size="11"
      font-weight="600" text-anchor="middle">LABEL</text>
<text x="CENTER_X" y="Y+36" fill="TEXT_MUTED" font-size="9"
      text-anchor="middle">sublabel</text>
```

Standard heights: 60px for simple services, 70–80px for labeled boxes, 100–120px for multi-line content.

### Region / cluster boundary

Dashed amber rectangle enclosing a logical group (e.g., "GDPO CORE"):

```svg
<rect x="X" y="Y" width="W" height="H" rx="12"
      fill="REGION_FILL" stroke="CORE_STROKE"
      stroke-width="1.5" stroke-dasharray="8,4"/>
<text x="X+20" y="Y+25" fill="CORE_STROKE" font-size="11"
      font-weight="700" letter-spacing="1">◆ REGION LABEL</text>
```

The `◆` (or `▸`, `⚠`, `◇`) glyph serves as a visual section marker — use consistently.

### Security-group style (transparent dashed box)

For sub-groupings within a region:

```svg
<rect x="X" y="Y" width="W" height="H" rx="8"
      fill="transparent" stroke="WARNING_STROKE"
      stroke-width="1" stroke-dasharray="4,4"/>
```

## Arrows

### Definitions

```svg
<defs>
  <marker id="arrowhead" markerWidth="10" markerHeight="7"
          refX="9" refY="3.5" orient="auto">
    <polygon points="0 0, 10 3.5, 0 7" fill="ARROW_COLOR"/>
  </marker>
  <marker id="arrowhead-emerald" markerWidth="10" markerHeight="7"
          refX="9" refY="3.5" orient="auto">
    <polygon points="0 0, 10 3.5, 0 7" fill="CORE_STROKE"/>
  </marker>
  <!-- One per accent color you use -->
</defs>
```

### Arrow types

| Purpose | Style |
|---|---|
| Standard data flow | solid 1.5px, `arrow`, `marker-end="url(#arrowhead)"` |
| Core method flow | solid 2px, core stroke, core arrowhead |
| Training loop / feedback | dashed 1.5px `stroke-dasharray="5,5"`, data stroke |
| Auth / priority / guarded flow | dashed 1.5px, warning stroke |
| Contrast marker (GRPO → GDPO) | solid, larger, slate |

### Z-order

SVG elements paint in document order. Draw arrows **early** (right after the grid) so they sit behind boxes. Then draw boxes on top.

### Masking arrows behind semi-transparent fills

Component boxes use translucent fills, so arrows behind them show through as washed-out lines. If you need a clean mask, lay an opaque base rect first. Use `#0f172a` in dark mode and `#ffffff` in light mode:

```svg
<!-- Opaque background mask -->
<rect x="X" y="Y" width="W" height="H" rx="6" fill="BOX_MASK"/>
<!-- Styled component on top -->
<rect x="X" y="Y" width="W" height="H" rx="6"
      fill="CORE_FILL" stroke="CORE_STROKE" stroke-width="1.5"/>
```

## Spacing discipline

This is where most diagrams go wrong. The rules:

- **Minimum vertical gap between stacked boxes:** 40px.
- **Inline connectors (small message buses, labels):** place *in* the gap, not overlapping the boxes.
- **Arrow length:** at least 30px of visible shaft. If two boxes are too close, move them apart.
- **Text-to-edge padding inside boxes:** 10px minimum on all sides.
- **Legend placement:** outside all boundary boxes. Compute the lowest boundary bottom, add ≥20px, place legend below that. Extend the SVG viewBox height if needed.

### Worked spacing example

```
Box A: y=70,   height=60   → bottom at y=130
Gap:   y=130 to y=170      → 40px gap
         (message bus at y=140, 20px tall → sits in middle)
Box B: y=170,  height=60   → bottom at y=230
```

**Wrong:** Box B at y=160 when Box A ends at y=130 (only 30px gap — too tight).
**Right:** Box B at y=170 (40px gap) with an optional inline element at y=140.

## Layout for paper diagrams

A paper diagram has three typical sections, stacked vertically:

1. **Main pipeline** (top): the left-to-right or top-to-bottom flow of the method. Most important part — give it the most real estate.
2. **Contrast panel** (middle, optional): the "why this beats prior work" comparison. Two side-by-side boxes — rose-colored for prior work, emerald for this paper. Include concrete numbers if the paper provides them (like GDPO's advantage values).
3. **Auxiliary detail** (bottom, optional): priority handling, loss decomposition, hyperparameter table — anything secondary the reader might care about.

Each section gets its own header line: `▸ SECTION NAME` in the accent color for that section.

## Summary cards (HTML output only)

Below the SVG, use a CSS grid of 3–6 cards capturing the paper's key points. One card per theme:

```html
<div class="card">
  <div class="card-header">
    <div class="card-dot COLOR"></div>
    <h3>Card title</h3>
  </div>
  <ul>
    <li>• Bullet one (one specific fact)</li>
    <li>• Bullet two</li>
  </ul>
</div>
```

Theme card styling:

- Dark: card `background: rgba(15, 23, 42, 0.5)`, border `#1e293b`, title `#ffffff`, body `#94a3b8`.
- Light: card `background: #ffffff`, border `#d8e0ea`, title `#0f172a`, body `#475569`, optional subtle `box-shadow: 0 12px 32px rgba(15, 23, 42, 0.08)`.

Suggested cards for a method paper:

1. **The Problem** (rose dot) — what failure mode the paper identifies
2. **The Fix** (emerald dot) — the method in 3–4 bullets
3. **Empirical Validation** (amber dot) — headline numbers with concrete deltas
4. **Secondary Insights** (violet dot) — priority handling, conditioning, etc.
5. **Design Choices to Note** (cyan dot) — reproduction gotchas
6. **Open Questions** (orange dot) — what the paper leaves unresolved

Bullet content should be specific. "Improves accuracy" is useless; "+6.3% pass@1 on AIME with DS-R1-1.5B" is useful.

## Checklist before committing the diagram

Walk through these before you declare done:

- [ ] Core contribution is emerald and visually dominant
- [ ] The selected `--bg-theme` palette is applied consistently to page, SVG canvas, cards, legend, arrows, masks, and text
- [ ] Light theme uses dark readable text and pale fills, not dark-theme colors pasted onto white
- [ ] Every box has a purpose — no decorative placeholders
- [ ] Every arrow has a clear source and target; no dangling lines
- [ ] Every region boundary contains what it labels; nothing spills out
- [ ] Legend is outside all boundaries
- [ ] ViewBox height accommodates the legend
- [ ] Key equations are inline in the flow, not buried in a separate panel
- [ ] The diagram would be comprehensible without the paper open alongside
- [ ] The contrast panel (if included) uses concrete numbers, not hand-waves
- [ ] No text overlaps another text; no text overlaps a stroke line
- [ ] Chinese labels (if applicable) have `Noto Sans SC` in the font stack
- [ ] File saved under `/mnt/user-data/outputs/` with a descriptive filename
- [ ] `present_files` called with the output path

## Rendering notes

**For PNG output via Playwright:** use `device_scale_factor=2` and `wait_for_timeout(1500)` after `networkidle` to let Google Fonts finish loading. Without the wait, fonts fall back to generic monospace.

**For SVG standalone:** the `<style>` block must use CDATA. Otherwise the `&` in the Google Fonts URL breaks XML parsing:

```svg
<style><![CDATA[
  @import url('https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&display=swap');
  text { font-family: 'JetBrains Mono', monospace; }
]]></style>
```


path: references/diagram-labels-cn.md
content: # 图示标签中文对照表

当使用 `--showcase-language cn` 时加载本文件。含义：图示中的结构性标签使用中文，通用技术术语保留英文。

## 字体注意事项

中文标签的字体栈必须包含中文字体：

```css
font-family: 'JetBrains Mono', 'Noto Sans SC', 'Courier New', monospace;
```

Google Fonts 引入：

```html
<link href="https://fonts.googleapis.com/css2?family=JetBrains+Mono:wght@400;500;600;700&family=Noto+Sans+SC:wght@400;500;600;700&display=swap" rel="stylesheet">
```

## 通用结构性标签

| 英文 | 中文 |
|---|---|
| Training Pipeline | 训练流水线 |
| Inference Pipeline | 推理流水线 |
| Input / Output | 输入 / 输出 |
| Encoder / Decoder | 编码器 / 解码器 |
| Core Contribution | 核心贡献 |
| Key Insight | 关键洞察 |
| Prior Work | 先前工作 |
| Baseline | 基线 |
| Ablation | 消融 |
| Method Overview | 方法概览 |
| System Architecture | 系统架构 |
| Dataset | 数据集 |
| Model | 模型 |
| Policy | 策略 |
| Reward / Loss | 奖励 / 损失 |
| Gradient Update | 梯度更新 |
| Feedback Loop | 反馈回路 |
| Legend | 图例 |
| Step 1 / Step 2 / Step 3 | 步骤 1 / 步骤 2 / 步骤 3 |

## 数据流 / 流程语义

| 英文 | 中文 |
|---|---|
| Data flow | 数据流 |
| Training loop | 训练循环 |
| Auth flow | 认证流 |
| Feedback / Propagation | 反馈 / 传播 |
| Sample / Sampling | 采样 |
| Evaluate | 评估 |
| Aggregate | 聚合 |
| Normalize | 归一化 |
| Update | 更新 |

## 机器学习常见术语

| 英文 | 中文 |
|---|---|
| Reinforcement Learning | 强化学习 |
| Supervised Fine-tuning | 监督微调 |
| Policy Optimization | 策略优化 |
| Advantage | 优势 |
| Rollout | 采样轨迹（或保留 rollout） |
| Rollout trajectory | 采样轨迹 |
| Batch | 批次 |
| Group | 组 |
| Per-reward / Per-sample | 逐奖励 / 逐样本 |
| Weighted sum | 加权求和 |
| Mean / Std (statistics) | 均值 / 标准差 |
| Clipping | 裁剪 |
| KL divergence | KL 散度 |
| PPO-clipped objective | PPO 裁剪目标 |
| Importance ratio | 重要性比率 |

## 保留英文（请勿翻译）

这些术语在中文语境下通常不翻译，保留英文更清晰：

- Transformer / Attention / Self-Attention
- Softmax / Sigmoid / ReLU / GELU
- LoRA / QLoRA / PEFT
- MoE (Mixture of Experts)
- RLHF / DPO / GRPO / PPO
- Tokenizer / Token / Embedding
- Logits / Probits
- Adam / AdamW / SGD
- Batch norm / Layer norm (这些是标准英文简写)
- Fine-tune (有时作动词使用时保留)

## 警告 / 结果语义（图示中经常出现）

| 英文 | 中文 |
|---|---|
| ✗ IDENTICAL — information collapse | ✗ 相同 — 信息坍塌 |
| ✓ DISTINCT — differences preserved | ✓ 不同 — 差异保留 |
| Collapsed | 坍塌 / 退化 |
| Stable convergence | 收敛稳定 |
| Training instability | 训练不稳定 |
| Diverges | 发散 |
| Outperforms | 优于 |
| Trade-off | 权衡 |

## 图示页脚格式

中文图示推荐页脚格式：

```
[论文简称] · [作者], [机构] · arXiv:[编号] ([日期])
```

例如：`GDPO · Liu 等, NVIDIA · arXiv:2601.05242 (2026 年 1 月)`

## 常见排版陷阱

- **中英混排时的间距**：中文与英文之间建议加半角空格，例如 "使用 GRPO 训练" 而非 "使用GRPO训练"。
- **等宽字体中的中文**：JetBrains Mono 不覆盖中文字符，Noto Sans SC 字符宽度与拉丁字符不等宽，视觉上会有不齐——这是预期行为，不要强制拉伸。
- **标点符号**：中文正文优先使用中文标点（，。："），但表格和紧凑列表中保留英文标点避免视觉拥挤。
- **数字**：始终使用阿拉伯数字，不要用中文数字（"3 次运行" 而非 "三次运行"）。


path: references/output-cn.md
content: # 中文输出结构

当用户使用中文或指定 `--cn` 时，使用本文件定义的所有章节标题与输出格式。
分析内容全程中文；专业英文术语（Transformer、softmax、ablation study 等）照常保留。
置信度标注保持英文：`[paper]` / `[inferred]` / `[external]`。

---

## 第 0 节 — 论文元数据

以紧凑表格呈现，每字段一行，不作评价：

| 字段 | 内容 |
|---|---|
| 标题 | |
| 作者与机构 | |
| 发表载体 / 状态 | 例："NeurIPS 2024 正式录用" 或 "arXiv 预印本，尚未同行评审" |
| 代码 / 数据可用性 | 已开源 / 未开源 / 部分开源 — 如有链接请附上 |
| 可重复性信号 | 注明论文是否报告：随机种子、置信区间、算力规格、数据集划分方式 |

---

## 第 1 节 — 研究问题与动机

依次回答以下三个问题，每问一段：

1. **本文解决的具体问题是什么？** 要求精确。不要复述摘要——用自己的语言重新表述，尽可能写成形式化目标（例如："在约束 Y 下最小化 X"）。

2. **现有方法为何在此失效？** 点名具体的失效模式——是二次复杂度、分布偏移、标注稀缺还是优化不稳定？需具体说明哪些先前方法失效以及原因。按实际情况标注 `[paper]` 或 `[inferred]`。

3. **为什么这个问题值得解决？** 联系真实的下游影响。如果论文对此论证不充分，请直接指出。

---

## 第 2 节 — 技术方案

这是分析的核心。要求精确，必要时使用数学表达。

**核心贡献（一句话）** — 格式："本文提出 [X]，通过 [机制]，实现了 [能力]，而先前工作因 [原因] 无法做到这一点。"

**方法流程** — 端到端梳理：
- 输入如何表征 / 编码？
- 关键架构组件或算法步骤是什么？
- 训练目标是什么？如有损失函数，请写出：$\mathcal{L} = ...$
- 训练与推理阶段是否存在行为差异（training-inference gap）？

**真正的新颖点** — 具体说明与先前工作的逻辑差异。不要泛泛说"改进了 X"，而是解释：先前工作做了什么假设，本文放弃或修改了哪个假设，以及为什么这一改变很重要。

**复杂度分析** — 分别给出训练和推理的时间复杂度与空间复杂度。论文中有明确说明的标 `[paper]`，需自行推导的标 `[inferred]`。

---

## 第 3 节 — 实验验证

**主要结果表** — 复现论文核心结果表的关键数字。所有数字标注 `[paper]`。

| 数据集 | 指标 | 先前 SOTA | 本文结果 | Δ |
|---|---|---|---|---|

**消融实验分析** — 如有消融实验，指出哪个模块贡献了主要增益，哪个贡献边际。如论文缺少消融实验，请明确标出——这是一个值得指出的弱点。

**统计严谨性** — 直接作答：
- 结果是否附有方差（标准差 / 置信区间）？
- 使用了多少个随机种子 / 运行次数？
- 是否进行了显著性检验？

如以上均未报告，请明确说明。这是衡量论文质量的重要信号。

**潜在混淆因素** — 检查以下几点：基线是否过弱、数据集选取是否有利于本文、超参数调优是否对本文方法更充分（对基线调优不足）、评估是否只在同分布数据上进行。

---

## 第 4 节 — 批判性评审

以持怀疑态度但立场公正的审稿人视角写作。要求具体——"需要更多实验"这类泛泛批评没有价值。

每条批评需说明：
- 问题是什么
- 是 `[paper]`-可证实的还是 `[inferred]` 的推断
- 严重程度（严重 / 中等 / 轻微）

至少覆盖以下方面：
- **方法层面的隐患**：可能不成立的假设、方法在边缘情况下的潜在失效、可扩展性限制
- **实验层面的问题**：缺失的基线、数据集覆盖不足、结果挑选风险
- **声明范围**：论文的叙述框架是否夸大了实验实际能证明的结论？
- **客观优点**：同样注明论文真正做得好的地方——好的评审应该是平衡的

---

## 第 5 节 — 综合总结

**TL;DR（30 秒摘要）** — 最多三句话，面向没有时间的研究者。涵盖：论文做了什么、核心结果是什么、最重要的局限是什么。

**创新类型判断** — 选择一项并简要说明理由：
- *范式转变*：提出了全新的问题框架或解决方案类别
- *方法突破*：在既有框架内引入了有力的新机制
- *工程进步*：在不改变核心思路的前提下提升了效率或规模
- *应用迁移*：将已知方法有效地迁移到新领域

**部署成熟度** — 这个方法在当下的实践中处于什么位置？要在生产环境中使用，还需要解决哪些问题？

**开放问题** — 列出本文留下的 2–3 个具体研究方向。要求具体，"更多实验"不是开放问题。

**复现注意事项** — 根据论文内容，哪些地方最可能让复现者踩坑？（例如：对某个超参数极度敏感、缺失关键预处理步骤、算力需求过高等）


path: references/venue-tiers.md
content: # Venue tiers and what they mean for paper evaluation

Use this when assessing how much scrutiny to apply and what peer review standards the paper was held to.

## Conference tiers (ML/AI/CV/NLP)

**Tier 1 — Highly selective, rigorous review (acceptance ~20–25%)**
- Machine learning: NeurIPS, ICML, ICLR
- Computer vision: CVPR, ICCV, ECCV
- NLP: ACL, EMNLP, NAACL
- Robotics/systems: CoRL, RSS, OSDI, SOSP

Papers here have passed multiple rounds of expert review. Methodological flaws are less common, but still exist. Novelty bar is high.

**Tier 2 — Solid venues, somewhat less selective**
- AAAI, IJCAI, AISTATS, UAI, COLING, EACL
- Domain-specific top venues (e.g., KDD for data mining, WWW for web)

Good work appears here routinely. Apply normal scrutiny.

**Tier 3 — Workshops, demos, extended abstracts**
- NeurIPS/ICML/ICLR workshops
- Findings of ACL/EMNLP

These are *not* peer reviewed to the same standard as main tracks. Treat claims with more skepticism. Ablation studies and baselines are often missing.

## arXiv preprints

No peer review. Quality varies enormously. Important signals:
- Does the paper acknowledge it is a preprint?
- Is there an accepted venue version somewhere?
- Does it compare to very recent arXiv work, or only published baselines?
- Is code released? (Increases credibility)

For high-profile preprints from well-known labs: still apply full critical scrutiny. Lab reputation ≠ paper quality.

## Journals

**Top-tier**: JMLR, TPAMI, IJCV, Artificial Intelligence, Nature Machine Intelligence

Journal papers typically have more thorough experiments and longer review cycles. But they may be behind the curve on very recent methods.

## What to say in Section 0

- For Tier 1 conferences: "Published at [venue] — peer reviewed to a high standard."
- For workshops: "Workshop paper — lighter review process; treat methodology claims with additional scrutiny."
- For arXiv: "Preprint — not peer reviewed. Assess methodology and experiments independently."
- For unknown venues: note this and apply conservative evaluation.


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)