@research-copilot/plugin 1.1.17 → 1.1.19

package/dist/skills/figure-designer/references/experimental-results.md

@@ -0,0 +1,127 @@
+# Experimental Results figure design
+
+## Table of contents
+
+1. Chart-type decision matrix
+2. Self-containment rule
+3. Scientific encoding rule
+4. Highlight Ours rule
+5. Honest axes rule
+6. Canvas sizing and style consistency
+7. Tool recommendations
+
+## 1. Chart-type decision matrix
+
+| Chart type | When to use | Design notes |
+|---|---|---|
+| Grouped bar | Multi-method comparison on multi-benchmark results | Ours in a bold dark colour; baselines in neutral grey; value labels on top of bars |
+| Line | Parameter sensitivity, training curves, trends over time or scale | Distinct colour + line style + marker combination per method (for example solid-circle, dashed-square, dotted-triangle); works in black and white |
+| Heatmap | Correlation matrices, attention visualisation, method-per-benchmark matrices | Continuous colour scale such as Viridis or Blue-White-Red; label each cell with the numeric value |
+| Scatter | Efficiency versus effectiveness trade-off | X axis efficiency metric, Y axis effectiveness metric; annotate each point with the method name; Ours in upper-right if the trade-off favours the paper |
+| Box plot | Distribution of results across multiple runs | More honest than reporting only the mean; shows variance |
+| Radar | Multi-dimensional capability comparison | Useful when comparing methods across several capability axes simultaneously |
+
+If none of these match the story, step back and ask whether the
+experiment is well-designed; a story that fits no chart type often
+has no clear conclusion.
+
+## 2. Self-containment rule
+
+Every experimental figure must be readable without the paper
+surrounding it. This means:
+
+- Every axis has a label with units.
+- Legend names every series that appears.
+- Caption's first sentence states the figure's main finding, not
+  just the setup. Example: "Figure 5: Performance comparison on
+  BIRD benchmark. Our method consistently outperforms all baselines
+  across model sizes."
+- Abbreviations used inside the figure are defined either in the
+  caption or inline.
+
+## 3. Scientific encoding rule
+
+Avoid chartjunk. Do not use:
+
+- 3D bar charts.
+- Background gradients.
+- Cross-hatch patterns for decoration.
+- Multiple overlapping legend keys.
+- Distorted aspect ratios that exaggerate small differences.
+
+Use dual encoding. Every series is distinguished by at least two
+visual channels (colour and shape, or colour and line style). A
+reader who prints the paper in black and white should still be
+able to tell curves apart.
+
+## 4. Highlight Ours rule
+
+If Ours dominates the baselines, distinguish it visually:
+
+- Dark or saturated colour versus neutral grey for baselines.
+- Bold outline or marker size larger than baselines.
+- Always appear in a consistent position (for example rightmost
+  column in bar charts, top of the legend).
+
+If Ours does not dominate (for example if the paper is a benchmark
+or evaluation paper where the point is that no method dominates),
+do not artificially highlight one method; let the reader see the
+parity.
+
+## 5. Honest axes rule
+
+- Y axis minimum should be chosen honestly. If all methods score
+  between 60 and 80 percent accuracy, starting at 0 makes
+  differences invisible; starting at 59 exaggerates them.
+  Reasonable start: 55 or 50 percent, with an axis break
+  explicitly shown if necessary.
+- Never truncate the top of the Y axis without indication.
+- Log scales are appropriate when dynamic range spans multiple
+  orders of magnitude; always label the scale as log.
+- Error bars or confidence intervals should appear when multiple
+  runs exist; report the methodology in the caption.
+
+## 6. Canvas sizing and style consistency
+
+### Canvas sizing
+
+Matplotlib defaults are designed for standalone viewing, not for
+LaTeX papers. Use a small canvas (roughly 150x100 points) so that
+fonts and lines scale up to readable size when inserted into a
+column.
+
+### Style consistency
+
+Create a `plot_utils.py` script early in the project. Define:
+
+- A palette (for example a 6-colour ColorBrewer qualitative scheme
+  with Ours = index 0).
+- Line widths (for example 1.5pt for data, 0.8pt for grid).
+- Font sizes (for example 9pt title, 8pt tick labels).
+- Figure dimensions per figure type.
+
+Every experimental figure imports from this script. The result is
+visual consistency across the paper, which reviewers register
+subconsciously as professionalism.
+
+## 7. Tool recommendations
+
+### Primary: Matplotlib or Seaborn
+
+- Code-generated; fully reproducible; version-controllable.
+- Can be scripted from experiment outputs without manual editing.
+- Scales to many figures with consistent styling.
+
+### Secondary: TikZ or PGFPlots
+
+- LaTeX-integrated; matches paper typography exactly.
+- Higher initial cost but cleanest visual integration.
+- Preferred by journals that expect LaTeX-native figures.
+
+### Avoid
+
+- Excel charts inserted as images. Quality is poor; styling is
+  inconsistent; impossible to regenerate from updated data.
+- Hand-edited plots (open the Matplotlib output in Illustrator and
+  edit). One-off success, zero reproducibility; the next reviewer
+  round will require regeneration from scratch.

package/dist/skills/figure-designer/references/motivated-example.md

@@ -0,0 +1,138 @@
+# Motivated Example (Figure 1) design
+
+## Table of contents
+
+1. Why Figure 1 matters
+2. Paradigm A: Running Example plus Failure Case
+3. Paradigm B: Existing vs Ours
+4. Paradigm C: Performance Teaser
+5. Design principles
+6. Tool recommendations
+
+## 1. Why Figure 1 matters
+
+Figure 1 is the single most important figure in the paper. It
+appears on page 1 or at the top of page 2, immediately after the
+Limitations paragraph in the Introduction. Its job is to convey in
+under 30 seconds (a) what problem the paper tackles and (b) why
+current methods do not solve it. Reviewers decide whether to read
+the rest of the paper partly based on this figure.
+
+Budget one to two working days on Figure 1. This is not excessive;
+it pays back across the entire review cycle.
+
+## 2. Paradigm A: Running Example plus Failure Case (recommended)
+
+The most persuasive paradigm. Show a real, specific scenario and
+then show what goes wrong under the current method.
+
+### Layout
+
+A two-panel or three-panel figure:
+
+- Panel 1 (top or left): the real input. Natural language query,
+  image, sensor trace, or whatever the task takes.
+- Panel 2 (middle or centre): what a current method produces. The
+  incorrect output. Highlight the error with red.
+- Panel 3 (optional, right or bottom): what the paper's method
+  produces or promises. The correct output. Highlight with green.
+
+### When to use
+
+- The problem is concrete and the failure is easy to show.
+- Text-to-SQL, code generation, visualisation, agent workflows.
+- Any case where a side-by-side output comparison exists.
+
+### Canonical example
+
+Text-to-SQL: show a natural-language query such as "find all
+professors who published at least 3 papers in 2024 and their
+departments", then show the current-method SQL missing a GROUP BY,
+yielding thousands of duplicated rows; then the correct SQL.
+
+## 3. Paradigm B: Existing vs Ours
+
+The figure splits into two side-by-side panels. Left shows how the
+existing method works and why it fails; right shows how the paper's
+method works and why it succeeds.
+
+### Layout
+
+Two vertical columns. Each column has:
+
+- A schematic of the method's internal structure.
+- An annotated failure or success indicator.
+- A one-line caption inside the panel naming the method.
+
+### When to use
+
+- The contribution is a structural change to the method's internal
+  architecture rather than a failure on a specific input.
+- Visualisation is possible at the mechanism level (operator graph,
+  data flow, component layout).
+
+### Canonical example
+
+AFlow (ICLR 2025) Figure 2 shows Node, Operator, Edge concepts
+side-by-side against traditional workflow representations.
+
+## 4. Paradigm C: Performance Teaser
+
+A carefully designed performance figure placed inside the
+Introduction as a preview of results.
+
+### Layout
+
+A compact chart (grouped bar, scatter, or radar) showing the
+paper's method clearly dominating baselines. The chart is paired
+with a one-sentence text annotation explaining what the reader is
+seeing.
+
+### When to use
+
+- The method's performance gain is the headline contribution and
+  is large enough to speak for itself.
+- Benchmark-style results are available.
+- The paper is short (conference style) and needs to hook the
+  reader with numbers.
+
+### When to avoid
+
+- Gains are marginal; a teaser shows this weakness unkindly.
+- The paper's value is qualitative (ambiguity handling, robustness)
+  and does not fit a single metric.
+
+## 5. Design principles
+
+- **Draft on paper first**. Sketch the figure by hand or on a
+  whiteboard. Show it to an advisor or collaborator. Iterate the
+  sketch before opening any software.
+- **Real entities only**. Name real queries, real datasets, real
+  outputs. Placeholder names ("Entity1", "X") undermine credibility.
+- **30-second test**. Show the figure to someone unfamiliar with the
+  paper. If they cannot describe the problem in 30 seconds, the
+  figure is not doing its job.
+- **Appears once, referenced throughout**. The same example in
+  Figure 1 should reappear in the Methodology (as a walkthrough)
+  and Experiments (as a case study).
+
+## 6. Tool recommendations
+
+### Primary: PowerPoint
+
+- Fast to iterate on layout.
+- Export as PDF preserves vector.
+- Fonts and alignment are easy to control.
+- Icons from free libraries (Iconfont, Flaticon) compose well.
+
+### Secondary: Figma
+
+- Collaborative editing.
+- Component-based design, reusable across figures.
+- More polished output for camera-ready.
+
+### Code snippets
+
+Generate syntax-highlighted code as a raster screenshot, then
+import into PowerPoint or Figma. Most code-highlighting tools
+(pygments-based, Carbon) export clean images.

package/dist/skills/figure-designer/references/solution-overview.md

@@ -0,0 +1,145 @@
+# Solution Overview (Methodology) figure design
+
+## Table of contents
+
+1. Why the Overview matters
+2. Paradigm A: Pipeline
+3. Paradigm B: System Architecture
+4. Paradigm C: Multi-layer
+5. Design principles
+6. Tool recommendations
+
+## 1. Why the Overview matters
+
+The Solution Overview figure sits at the top of the Methodology
+section (typically Figure 2 or the first figure of Section 3). Its
+job is to give a reader who skips prose a complete mental map of
+the method: what the inputs are, what the stages are, what the
+outputs are, and how components interact.
+
+A reader should be able to consult this figure at any point while
+reading the subsequent technical subsections and re-locate where
+they are in the method.
+
+## 2. Paradigm A: Pipeline
+
+The most common paradigm. A left-to-right (or top-to-bottom)
+sequence of stages: input to stage 1 to stage 2 to output. Each
+stage is a named box; sub-modules fit inside the box.
+
+### Layout
+
+- Canvas: wide, two to three times as wide as tall.
+- Three to five large stage boxes from left to right.
+- Each stage box contains sub-modules as small boxes.
+- Arrows between stages indicate data flow; labelled arrows
+  indicate specific data types.
+- Inputs on the far left; outputs on the far right.
+
+### When to use
+
+- The method is a multi-stage data transformation.
+- Each stage is independent of the others and can be understood
+  separately.
+- Text-to-SQL methods, data cleaning pipelines, agent workflows.
+
+### Canonical example
+
+AFlow (ICLR 2025) Figure 3: three columns (Search Space; Search
+via AFLOW; Search Result) with clear left-to-right flow.
+
+## 3. Paradigm B: System Architecture
+
+Used when the method is a system with interacting components rather
+than a linear pipeline. A large outer box represents the system
+boundary; internal boxes represent components; arrows show data
+flow and control flow within the system.
+
+### Layout
+
+- Canvas: square or slightly wider than tall.
+- Outer rectangle labelled with the system name.
+- Four to eight internal component boxes, arranged by
+  responsibility (front-end, back-end, data store, orchestrator).
+- Arrows indicate message passing or data flow.
+- Colour-code by component category (data, compute, interface).
+
+### When to use
+
+- The paper presents a system with multiple interacting agents,
+  modules, or services.
+- Components run concurrently rather than sequentially.
+- Feedback loops matter (the output of one component feeds back to
+  another).
+
+### Canonical example
+
+Alpha-SQL (ICML 2025) Figure 3: shows the MCTS framework including
+the LLM-as-action-model, the search tree expansion process, and
+the self-supervised reward feedback loop.
+
+## 4. Paradigm C: Multi-layer
+
+Used when the method has hierarchical structure or multiple phases
+that differ fundamentally (offline versus online, training versus
+inference, macro versus micro).
+
+### Layout
+
+- Canvas: vertically divided into two or three horizontal layers.
+- Each layer represents one phase or abstraction level.
+- Arrows between layers show how outputs of one layer feed into
+  another.
+- Layers are labelled (for example, "Offline" and "Online", or
+  "Training" and "Inference").
+
+### When to use
+
+- The method separates preprocessing from runtime execution.
+- Different components run at different frequencies.
+- The method has a training phase and an inference phase with
+  different behaviours.
+
+### Canonical example
+
+LEAD (VLDB 2026) Figure 3: upper row shows Offline setup; lower
+row shows Online selection integrated with training. Cross-layer
+arrows show data flow.
+
+## 5. Design principles
+
+- **Modular**: each component is a named box. Users can trace a
+  component into its corresponding subsection.
+- **Clear data flow**: arrows are explicit and do not cross where
+  crossing can be avoided.
+- **Hierarchy visible**: colour, size, or position distinguishes
+  levels (primary components larger; auxiliary components smaller
+  or grey).
+- **Names match prose**: every component's name in the figure
+  appears verbatim in a methodology subsection title. If the figure
+  says "Hotspot Detector", the paper says "Section 3.2 Hotspot
+  Detector".
+- **Inputs and outputs explicit**: the figure shows the overall
+  input and output of the method at its boundary.
+
+## 6. Tool recommendations
+
+### Primary: draw.io (also called diagrams.net) or PowerPoint
+
+- Grid snapping keeps alignment clean.
+- Shape libraries cover typical architecture components.
+- Exports to PDF as vector.
+
+### Secondary: Figma or TikZ
+
+- Figma for polish and team collaboration.
+- TikZ for LaTeX-integrated styling consistency; higher initial
+  investment but yields the cleanest look.
+
+### Avoid
+
+- Freehand drawing tools (Procreate, GoodNotes) for anything beyond
+  early sketches. The output lacks alignment and looks unprofessional
+  in a paper.
+- Generic diagram auto-generators; they do not understand paper-
+  figure conventions.

package/dist/skills/figure-designer/references/tools.md

@@ -0,0 +1,124 @@
+# Figure tool matrix
+
+## Table of contents
+
+1. Decision heuristic
+2. PowerPoint and Keynote
+3. Figma
+4. draw.io (diagrams.net)
+5. Matplotlib and Seaborn
+6. TikZ and PGFPlots
+7. Plotly
+8. OmniGraffle
+9. What to avoid
+
+## 1. Decision heuristic
+
+| Figure type | Primary tool | Alternative | Reason |
+|---|---|---|---|
+| Motivated Example (Figure 1) | PowerPoint | Figma | Mixed content: text, icons, code, arrows |
+| Solution Overview (pipeline, architecture, multi-layer) | draw.io | PowerPoint, TikZ | Need clear modular layout, aligned grids |
+| Experimental Results (bar, line, heatmap, scatter, etc.) | Matplotlib + Seaborn | TikZ + PGFPlots | Reproducible, scriptable, versioned |
+| Schema or relation diagrams | draw.io | TikZ | Standard database diagram conventions |
+| Icons and logos | Figma | Iconfont, Flaticon | Clean vector editing |
+
+Decide the figure type first; each tool shines on a specific type.
+Do not try to make one tool do all jobs.
+
+## 2. PowerPoint and Keynote
+
+- Fast iteration on layout.
+- Export as PDF preserves vector.
+- Font and alignment controls are reasonable.
+- Free on most institutional licenses.
+
+Best for early drafts, Figure 1 designs, and any figure with mixed
+content (text blocks, icons, arrows, embedded code snippets).
+
+Weakness: not reproducible from data; every edit is manual.
+
+## 3. Figma
+
+- Component-based; build reusable elements across figures.
+- Collaboration on a shared canvas.
+- Cleanest output for polished camera-ready Figure 1.
+- Web-based; no local install required.
+
+Best for polishing a Motivated Example or Solution Overview after
+the layout is stable.
+
+Weakness: browser-only; offline editing is limited.
+
+## 4. draw.io (diagrams.net)
+
+- Free, cross-platform, offline-capable.
+- Grid snapping keeps pipeline and architecture diagrams aligned.
+- Shape libraries cover typical computer-science diagramming needs.
+- Export as PDF or SVG.
+
+Best for Solution Overview figures that are pipelines or system
+architectures.
+
+Weakness: visual polish is lower than Figma or OmniGraffle.
+
+## 5. Matplotlib and Seaborn
+
+- Code-generated; fully reproducible from data.
+- Scriptable; regenerate all experiment figures after each
+  experiment re-run.
+- Scales to dozens of figures with shared styling.
+- Python-native; integrates with experiment scripts.
+
+Best for every experimental results figure.
+
+Weakness: defaults are ugly; always import a shared `plot_utils.py`
+for consistent styling.
+
+## 6. TikZ and PGFPlots
+
+- Native LaTeX; exact typography match with paper text.
+- Vector-perfect output.
+- Highest effort and steepest learning curve.
+
+Best for camera-ready figures in journals that expect TikZ-quality
+typography.
+
+Weakness: high cost for early drafts; switch to TikZ only after the
+figure design is stable.
+
+## 7. Plotly
+
+- Interactive; good for supplementary material or HTML appendices.
+- Export to static PNG or PDF for paper inclusion.
+
+Best for exploratory analysis and supplementary interactive
+figures.
+
+Weakness: default typography differs from academic norms; static
+export quality is below Matplotlib for paper inclusion.
+
+## 8. OmniGraffle
+
+- Professional diagram quality.
+- Native macOS only.
+- Paid.
+
+Best for polished Solution Overview figures if the author already
+uses macOS and has an OmniGraffle license.
+
+Weakness: macOS-only limits collaboration with Windows or Linux
+co-authors.
+
+## 9. What to avoid
+
+- **Excel charts inserted as images**. Poor quality, inconsistent
+  styling, difficult to regenerate.
+- **Hand-edited Matplotlib output in Illustrator**. One-off
+  result; breaks on every data update.
+- **Generic online diagram generators** with non-academic
+  conventions. The figure will look out of place in a top-venue
+  paper.
+- **Procreate, GoodNotes, Notability** for anything beyond early
+  hand sketches. Freehand drawing lacks alignment discipline.
+- **AI image generators** for paper figures. They cannot produce
+  the structured content academic figures require.