scientify 2.1.0 → 3.1.0

package/skills/write-paper/references/figures-manifest-template.md

@@ -0,0 +1,44 @@
+# Figures Manifest Template
+
+Use this structure for `paper/figures_manifest.md`.
+
+This file is the single source of truth for how a figure supports claims, how it is introduced in prose, and how it should be rendered in LaTeX.
+
+```yaml
+- figure_id: "fig-kv2-tradeoff-overview"
+  file_path: "paper/figures/kv2_tradeoff_overview.pdf"
+  latex_label: "fig:kv2-tradeoff-overview"
+  section: "main_results"
+  placement_hint: "figure[t]"
+  caption_short: "KV2 versus INT4-FIFO and quant-family baselines under the simulator protocol."
+  caption_long: "KV2 improves TTFT relative to INT4-FIFO while preserving the stated quality guard. The figure compares the main tradeoff surface across the selected quant-family baselines under the shared simulator protocol."
+  takeaway_sentence: "KV2 improves TTFT relative to INT4-FIFO, but the strongest bytes-efficiency challenger remains KVQuant-3bit-1% under the same harness."
+  callout_sentence: "Figure \\ref{fig:kv2-tradeoff-overview} compares KV2 with INT4-FIFO and quant-family baselines under the shared simulator protocol."
+  baseline: "INT4-FIFO"
+  evidence_type: "simulator"
+  source_metrics:
+    - "mean_ttft_gain_vs_int4_pct"
+    - "mean_bytes_gain_vs_int4_pct"
+  source_files:
+    - "experiment_res.md"
+    - "Comparision-KV2/results/kv2_compare_quant_family_local_20260329.md"
+  supports_claim_ids:
+    - "claim-001"
+    - "claim-003"
+  must_appear_before_claim_ids:
+    - "claim-001"
+```
+
+Rules:
+
+- Use one entry per figure, not one entry per paragraph.
+- `section` should name the manuscript module that owns the figure, such as `main_results`, `experimental_protocol`, or `ablations`.
+- `placement_hint` must already be TeX-oriented, for example `figure[t]`, `figure[b]`, `figure* [t]`, or `inline_reference_only`.
+- `caption_short` is for the optional short caption in `\caption[...]`.
+- `caption_long` must include the scientific meaning, the comparison target, and the relevant scope or protocol note when needed.
+- `takeaway_sentence` is the one-sentence interpretation the prose should not forget to make explicit.
+- `callout_sentence` is the first sentence that should introduce the figure in the body text.
+- `supports_claim_ids` lists which claims the figure directly supports.
+- `must_appear_before_claim_ids` lists the claims that should not appear before the reader has seen or been introduced to this figure.
+
+If a headline claim is table-only or text-only evidence, do not create a fake figure entry. Instead, say so explicitly in the results paragraph and keep the claim anchored to a table or source artifact.

package/skills/write-paper/references/latex/README.md

@@ -0,0 +1,22 @@
+# LaTeX Starter Bundle
+
+This starter bundle is copied into `paper/` when a new research workspace is created.
+
+It provides:
+
+- `manuscript.tex` as the top-level entry point
+- `sections/*.tex` for section-by-section drafting
+- `references.bib` as the bibliography placeholder
+- `build_paper.sh` to compile the PDF with `tectonic`
+
+Expected outputs after running the build script:
+
+- `paper/build/manuscript.pdf`
+- `paper/build/build.log`
+- `paper/build/build_errors.md` when compilation fails
+
+Notes:
+
+- The default bibliography commands in `manuscript.tex` are commented out to keep the first build path simple.
+- Uncomment the bibliography lines after citations and BibTeX entries are ready.
+- The starter bundle is modular. Keep the core sections, then selectively enable optional modules such as `related_work`, `ablations`, or `discussion_scope` when the paper shape actually needs them.

package/skills/write-paper/references/latex/build_paper.sh

@@ -0,0 +1,41 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+PAPER_DIR="$(cd "$(dirname "$0")" && pwd)"
+BUILD_DIR="$PAPER_DIR/build"
+LOG_PATH="$BUILD_DIR/build.log"
+ERROR_PATH="$BUILD_DIR/build_errors.md"
+
+mkdir -p "$BUILD_DIR"
+
+if ! command -v tectonic >/dev/null 2>&1; then
+  cat >"$ERROR_PATH" <<'EOF'
+# Paper Build Error
+
+`tectonic` was not found in `PATH`.
+
+Install `tectonic` first, then rerun:
+
+```bash
+bash paper/build_paper.sh
+```
+EOF
+  exit 1
+fi
+
+cd "$PAPER_DIR"
+
+if tectonic --outdir "$BUILD_DIR" manuscript.tex >"$LOG_PATH" 2>&1; then
+  rm -f "$ERROR_PATH"
+else
+  {
+    echo "# Paper Build Error"
+    echo
+    echo "The LaTeX build failed. See \`paper/build/build.log\` for the full compiler output."
+    echo
+    echo '```text'
+    tail -n 80 "$LOG_PATH" || true
+    echo '```'
+  } >"$ERROR_PATH"
+  exit 1
+fi

package/skills/write-paper/references/latex/manuscript.tex

@@ -0,0 +1,39 @@
+\documentclass[11pt]{article}
+
+\usepackage[margin=1in]{geometry}
+\usepackage[T1]{fontenc}
+\usepackage[utf8]{inputenc}
+\usepackage{microtype}
+\usepackage{amsmath,amssymb}
+\usepackage{booktabs}
+\usepackage{graphicx}
+\usepackage{xcolor}
+\usepackage{hyperref}
+
+\title{Paper Title Placeholder}
+\author{Author Placeholder}
+\date{}
+
+\begin{document}
+
+\maketitle
+
+\input{sections/abstract}
+\input{sections/introduction}
+\input{sections/problem_setup}
+\input{sections/method_system}
+\input{sections/experimental_protocol}
+\input{sections/main_results}
+
+% Optional modules: enable only if the current paper shape needs them.
+% \input{sections/related_work}
+% \input{sections/ablations}
+% \input{sections/discussion_scope}
+
+\input{sections/conclusion}
+
+% Uncomment after citations and BibTeX entries are ready.
+% \bibliographystyle{plain}
+% \bibliography{references}
+
+\end{document}

package/skills/write-paper/references/latex/references.bib

@@ -0,0 +1,10 @@
+% Add BibTeX entries here.
+%
+% Example:
+%
+% @article{example2026,
+%   title={Example Title},
+%   author={Example, A. and Example, B.},
+%   journal={arXiv preprint arXiv:2601.00001},
+%   year={2026}
+% }

package/skills/write-paper/references/latex/sections/ablations.tex

@@ -0,0 +1,3 @@
+\section{Ablations and Additional Analysis}
+
+Add ablations, sensitivity analysis, or secondary result slices here. Keep them clearly separated from headline results.

package/skills/write-paper/references/latex/sections/abstract.tex

@@ -0,0 +1,3 @@
+\begin{abstract}
+State the problem, the proposed method or system, one supported quantitative result, and the scope boundary. Keep every claim aligned with `claim_inventory.md`.
+\end{abstract}

package/skills/write-paper/references/latex/sections/conclusion.tex

@@ -0,0 +1,3 @@
+\section{Conclusion}
+
+Summarize the strongest supported claims only. If there is no separate boundary surface elsewhere, place one short scope-boundary sentence here. Do not introduce new claims here.

package/skills/write-paper/references/latex/sections/discussion_scope.tex

@@ -0,0 +1,7 @@
+\section{Discussion / Scope Note}
+
+% Use this optional module only when the paper benefits from a dedicated
+% place to separate observation from interpretation or to state the evidence
+% boundary explicitly. Do not enable it by default.
+
+Separate observed results from interpretation, and make the current evidence boundary explicit only if this paper shape needs a dedicated scope note.

package/skills/write-paper/references/latex/sections/experimental_protocol.tex

@@ -0,0 +1,3 @@
+\section{Experimental Protocol}
+
+State the baselines, datasets or workloads, guardrails, quality constraints, and evidence boundary.

package/skills/write-paper/references/latex/sections/introduction.tex

@@ -0,0 +1,3 @@
+\section{Introduction}
+
+Introduce the problem, why it matters, and what gap the paper addresses. Do not introduce unsupported result claims here.

package/skills/write-paper/references/latex/sections/main_results.tex

@@ -0,0 +1,9 @@
+\section{Main Results}
+
+% Draft this section from paper/claim_inventory.md and paper/figures_manifest.md.
+% For figure-backed claims, introduce the figure with its callout_sentence
+% before or at the first discussion point, then keep the figure block fields
+% aligned with file_path, caption_short, caption_long, latex_label, and
+% placement_hint from the manifest.
+
+State the supported result claim, the quantitative evidence, the named baseline, and the boundary note for each main-results paragraph.

package/skills/write-paper/references/latex/sections/method_system.tex

@@ -0,0 +1,3 @@
+\section{Method / System}
+
+Describe the method or system design. Separate implementation detail from claimed contribution.

package/skills/write-paper/references/latex/sections/problem_setup.tex

@@ -0,0 +1,3 @@
+\section{Problem Setup}
+
+Define the task, assumptions, evaluation setting, and any notation needed to understand the rest of the paper.

package/skills/write-paper/references/latex/sections/related_work.tex

@@ -0,0 +1,3 @@
+\section{Related Work}
+
+Use this optional section when the paper benefits from a direct comparison to the closest prior families. Keep it focused on the dimensions that matter for this manuscript rather than turning it into a survey.

package/skills/write-paper/references/paper-template.md

@@ -0,0 +1,155 @@
+# Paper Draft
+
+This is a modular paper template, not a fixed universal outline.
+
+Core sections should usually stay:
+
+- Abstract
+- Introduction
+- Problem Setup
+- Method / System
+- Experimental Protocol
+- Main Results
+- Conclusion
+
+Optional modules should be added only when they help the current paper:
+
+- Related Work
+- Ablations and Additional Analysis
+- Discussion / Scope Note
+- Boundary / Scope surface
+
+Choose the paper shape before filling the outline:
+
+- `result_note`
+  - use the core sections only
+- `systems_full`
+  - enable optional modules only when they carry real argumentative load
+- `artifact_summary`
+  - keep the shape lean and boundary-aware
+- `workshop_short`
+  - compress setup and method, and avoid optional modules unless required
+
+## Abstract
+
+Use exactly four functional sentence types in this order:
+
+1. problem statement
+2. method or system statement
+3. strongest quantitative result
+4. scope boundary or evidence boundary
+
+Do not use unsupported adjectives such as "strong", "significant", or "robust" without a metric.
+Keep the abstract to four sentences in the default profile.
+
+## 1. Introduction
+
+Paragraph 1:
+- define the problem and why it matters
+
+Paragraph 2:
+- explain the gap in prior methods or current workflow
+
+Paragraph 3:
+- summarize contributions without introducing unsupported result claims
+
+Every claimed contribution here must map to a later section.
+Keep the default introduction to three compact paragraphs.
+
+## Optional: Related Work
+
+If a related-work section is needed, keep it focused on:
+
+- closest comparison family
+- direct difference in target, assumptions, or evidence type
+- what is compared directly versus what is only contextualized
+
+Do not turn related work into a generic survey dump.
+
+## 2. Problem Setup
+
+Define task scope, assumptions, notation, evaluation target, and any constraints needed to interpret the paper.
+Keep this section definition-heavy and result-light.
+
+## 3. Method / System
+
+Describe the system or method design.
+
+Separate:
+- what is implemented
+- what is claimed as a contribution
+- what is only an engineering choice
+
+Prefer short subsections or short paragraphs over one long implementation block.
+
+## 4. Experimental Protocol
+
+State:
+
+- baseline family
+- evaluation setup
+- quality guard or protocol constraint
+- evidence boundary (`simulator`, `local_runtime`, or `runtime`)
+
+State the evaluation regime before making any performance claim.
+
+## 5. Main Results
+
+Every paragraph in this section must:
+
+- map back to at least one `claim_id`
+- contain at least one quantitative statement
+- name a baseline or comparison target
+- state a takeaway, not just restate a figure
+
+Recommended paragraph structure:
+
+1. claim sentence
+2. evidence sentence
+3. comparison sentence
+4. boundary or caveat sentence
+
+Figure/text rules:
+
+- Introduce each figure with a callout sentence before or at first discussion.
+- A figure callout must contain a takeaway, not just "Figure X shows ..."
+- If a figure supports a headline claim, the text should also name the relevant `claim_id` or clearly map to it.
+- Prefer shorter result paragraphs with one main claim each.
+
+## 6. Ablations and Additional Analysis
+
+Keep secondary analysis separate from headline results.
+
+Do not let ablations silently carry the main claim.
+Use this section to explain or stress-test the main result, not to replace it.
+
+## Optional: Discussion / Scope Note
+
+Use this module when the paper needs an explicit place to:
+
+- separate observation from interpretation
+- state evidence boundary
+- mark what is intentionally not claimed
+- explain where the current artifact does not generalize
+
+This can be a short section, a subsection, or a structured paragraph block.
+
+## Optional: Boundary / Scope Surface
+
+Do not force a dedicated limitations section by default.
+
+Pick the lightest surface that fits the current paper:
+
+- one short caveat paragraph in `Main Results`
+- one short scope paragraph in `Conclusion`
+- an optional `Discussion / Scope Note`
+- a standalone `paper/boundary_notes.md` during drafting
+
+Use a dedicated limitations section only if the venue or review process explicitly expects one.
+
+## 7. Conclusion
+
+Restate only the strongest supported claims.
+
+Do not introduce a new claim, baseline, or interpretation here.
+Keep the conclusion to 1-2 tight paragraphs in the default profile.

package/skills/write-paper/references/paragraph-contract.md

@@ -0,0 +1,139 @@
+# Paragraph Contract
+
+Use these rules when drafting sections for `paper/draft.md` or `paper/sections/*.tex`.
+
+## Global Rules
+
+- Prefer short paragraphs with one clear function over long mixed-purpose paragraphs.
+- Every paragraph should have a dominant job: setup, claim, evidence, comparison, interpretation, or boundary note.
+- If a paragraph mixes observation and interpretation, split it.
+- If a paragraph makes a comparison, it must name the baseline or comparison target explicitly.
+- If a paragraph cannot be tied to a source artifact, do not present it as a result paragraph.
+
+## Abstract
+
+- Sentence 1: define the problem.
+- Sentence 2: state the method, system, or intervention.
+- Sentence 3: state the strongest supported quantitative result.
+- Sentence 4: state the scope boundary or evidence boundary.
+
+Rules:
+
+- Use only `confidence=high` claims here.
+- Do not use praise words unless a number and baseline follow in the same sentence.
+- Keep the abstract to exactly four sentences in the default template.
+
+## Introduction
+
+- Paragraph 1: problem and motivation
+- Paragraph 2: gap or limitation in current approaches
+- Paragraph 3: contribution summary
+
+Rules:
+
+- Do not preview unsupported result claims.
+- Contributions must map to later sections.
+- Keep the default introduction to three short paragraphs unless the venue profile says otherwise.
+
+## Problem Setup
+
+- Paragraph 1: define the task, setting, or operational problem.
+- Paragraph 2: define evaluation target, constraints, and success criteria.
+
+Rules:
+
+- Prefer definitions and scope boundaries over motivation language.
+- Do not smuggle results into the setup section.
+
+## Method / System
+
+- Paragraph 1: core design idea
+- Paragraph 2: implementation structure
+- Paragraph 3: what is claimed as the contribution versus what is only an engineering choice
+
+Rules:
+
+- Separate contribution-bearing design from ordinary implementation detail.
+- If a design choice is not defended later, avoid overselling it here.
+
+## Experimental Protocol
+
+- Paragraph 1: baselines and comparison family
+- Paragraph 2: workloads, data, or evaluation setting
+- Paragraph 3: quality guardrails and evidence boundary
+
+Rules:
+
+- Always state the evaluation regime before summarizing the result.
+- Make simulator, local-runtime, and runtime scopes explicit.
+
+## Main Results
+
+Each paragraph must contain:
+
+1. a claim sentence
+2. an evidence sentence
+3. a baseline comparison sentence
+4. a boundary or caveat sentence
+
+Rules:
+
+- Every paragraph must map to at least one `claim_id`.
+- Every paragraph must include at least one quantitative statement.
+- If the paragraph compares methods, it must name the baseline explicitly.
+- Each figure should be introduced by a callout sentence before or at first discussion.
+- A result paragraph should usually be 4-6 sentences, not a long narrative block.
+
+## Ablations and Additional Analysis
+
+- Paragraph 1: what secondary question is being tested
+- Paragraph 2+: measured answer with comparison and takeaway
+
+Rules:
+
+- Keep ablations secondary. Do not let them silently carry the paper's main claim.
+- If an ablation becomes central to the story, move the corresponding claim into `Main Results`.
+
+## Discussion
+
+- Start from an observed result.
+- Then add interpretation.
+
+Rules:
+
+- Keep observation and interpretation separable.
+- Do not hide speculation inside result phrasing.
+
+## Related Work
+
+- Paragraph 1: closest comparison family
+- Paragraph 2: key difference in assumption, target, or evidence
+- Paragraph 3: what is compared directly versus what is only contextualized
+
+Rules:
+
+- Do not turn related work into a survey dump.
+- Compare on dimensions that matter for this paper: target, evidence type, baseline family, and scope.
+
+## Boundary / Scope Surface
+
+- State the evidence boundary.
+- State what is missing.
+- State what is intentionally not claimed.
+
+Rules:
+
+- Put this material in the lightest surface that fits the current paper: `Main Results`, `Discussion / Scope Note`, `Conclusion`, or `paper/boundary_notes.md`.
+- Name the missing validation directly.
+- If a claim depends on simulator evidence, say so explicitly.
+
+## Conclusion
+
+- Restate the strongest supported claims only.
+
+Rules:
+
+- No new claim.
+- No new baseline comparison.
+- No new interpretation that did not appear earlier.
+- Prefer 1-2 tight paragraphs over a long recap.

package/skills/write-paper/references/paragraph-examples.md

@@ -0,0 +1,171 @@
+# Paragraph Examples
+
+Use these as movable writing patterns, not as a fixed chapter-by-chapter script.
+
+The same pattern can appear in different places depending on the paper shape:
+
+- a framing paragraph can appear in `Introduction`, `Problem Setup`, or the opening of a short report
+- a quantified claim paragraph can appear in `Main Results`, an artifact summary, or a rebuttal appendix
+- a boundary paragraph can appear in `Main Results`, `Discussion / Scope Note`, `Conclusion`, or `paper/boundary_notes.md`
+
+## Pattern 1: Framing the Problem
+
+### Bad
+
+Inference optimization has become very important in many domains. Many prior methods have tried to solve this problem. Our method is better and more comprehensive than existing approaches.
+
+Problems:
+
+- generic setup
+- no specific gap
+- unsupported comparative claim
+
+### Better
+
+Fixed-budget inference systems often face a hard tradeoff between latency and quality. Existing baselines expose this tradeoff, but they do not make it easy to preserve quality under the same resource envelope. This work targets that gap and focuses on artifact-backed tradeoff improvement rather than unconstrained speedup claims.
+
+Why this is better:
+
+- defines the problem concretely
+- names the gap
+- avoids unsupported boasting
+
+## Pattern 2: Quantified Claim
+
+### Bad
+
+KV2 shows strong and promising gains across the board. The method appears robust and significantly better than prior approaches. These results suggest the design is highly effective.
+
+Problems:
+
+- no number
+- no baseline
+- no evidence boundary
+- interpretation blended into the result claim
+
+### Better
+
+KV2 improves mean TTFT by 17.53% versus INT4-FIFO under the stated simulator protocol. The comparison is measured under `quality_penalty_mean <= 0.02` and is anchored in `claim-001`. This result supports a lower-latency tradeoff within simulator evaluation, but it does not yet establish full runtime behavior.
+
+Why this is better:
+
+- includes a metric
+- names the baseline
+- points to a claim anchor
+- states the evidence boundary
+
+## Pattern 3: Figure-Led Result
+
+### Bad
+
+Figure 2 shows the main result.
+
+Problems:
+
+- no takeaway
+- no metric
+- no explanation of why the figure matters
+
+### Better
+
+Figure 2 summarizes the latency-quality tradeoff and shows that KV2 reduces mean TTFT relative to INT4-FIFO under the stated simulator guardrail. This figure supports `claim-001` and should be read as simulator evidence rather than runtime validation.
+
+Why this is better:
+
+- states the takeaway
+- names the comparison target
+- marks the evidence boundary
+
+## Pattern 4: Comparison Paragraph
+
+### Bad
+
+Our method outperforms the baseline in most cases and is generally better than previous approaches.
+
+Problems:
+
+- does not say which baseline
+- does not say what metric improved
+- hides regime differences behind “most cases”
+
+### Better
+
+Relative to INT4-FIFO, KV2 improves mean TTFT while preserving the stated quality guard, but it does not exceed KVQuant-3bit-1% on bytes/request under the same harness. This makes the current result a balanced tradeoff claim rather than a blanket “best overall” claim.
+
+Why this is better:
+
+- names both comparison targets
+- distinguishes the winning dimension from the losing one
+- prevents overclaim
+
+## Pattern 5: Interpretation Paragraph
+
+### Bad
+
+These results prove that KV2 is generally superior and will likely work well across all realistic deployments.
+
+Problems:
+
+- turns a bounded observation into a general claim
+- mixes evidence and speculation
+- overgeneralizes scope
+
+### Better
+
+The measured simulator results indicate a lower-latency tradeoff under the reported protocol. One plausible interpretation is that the KV2 design better preserves quality under a fixed budget, but that interpretation still requires runtime validation and broader workload coverage.
+
+Why this is better:
+
+- starts from the observed result
+- labels interpretation as interpretation
+- keeps the open validation gap visible
+
+## Pattern 6: Boundary Paragraph
+
+### Bad
+
+There are some limitations and future work remains.
+
+Problems:
+
+- vague
+- hides the real evidence boundary
+- says nothing actionable
+
+### Better
+
+The current artifact does not establish full runtime behavior because the headline comparisons are still simulator-backed. Runtime smoke tests, broader workloads, and missing baseline replications remain open, so the paper intentionally avoids stronger deployment claims.
+
+Why this is better:
+
+- names the missing validation
+- states what is not claimed
+- ties the boundary to the actual artifact
+
+## Pattern 7: Closing Sentence
+
+### Bad
+
+Overall, our method is a highly robust and comprehensive solution for efficient inference.
+
+Problems:
+
+- empty praise
+- no measurable support
+- overgeneralized scope
+
+### Better
+
+Overall, the current artifact supports lower-latency tradeoffs under the reported simulator protocol, while runtime validation and broader workload coverage remain open.
+
+Why this is better:
+
+- closes on the strongest supported claim
+- keeps the scope visible
+- avoids turning the conclusion into a slogan
+
+## How To Use These Examples
+
+- Pick the pattern that matches the paragraph's job, not the section name.
+- If one paragraph is trying to do two jobs, split it.
+- Prefer adapting a pattern to the current evidence base over copying its sentence order exactly.