scientify 2.1.0 → 3.1.0

package/skills/research-review/SKILL.md

@@ -15,16 +15,15 @@ metadata:
 
 **Don't ask permission. Just do it.**
 
-**Workspace:** `$W` = working directory provided in task parameter.
 
 ## Prerequisites
 
 | File | Source |
 |------|--------|
-| `$W/ml_res.md` | /research-implement |
-| `$W/project/` | /research-implement |
-| `$W/plan_res.md` | /research-plan |
-| `$W/survey_res.md` | /research-survey |
+| `ml_res.md` | /research-implement |
+| `project/` | /research-implement |
+| `plan_res.md` | /research-plan |
+| `survey_res.md` | /research-survey |
 
 **If `ml_res.md` is missing, STOP:** "需要先运行 /research-implement 完成代码实现"
 
@@ -32,7 +31,7 @@ metadata:
 
 | File | Content |
 |------|---------|
-| `$W/iterations/judge_v{N}.md` | 每轮审查报告 |
+| `iterations/judge_v{N}.md` | 每轮审查报告 |
 
 最终报告中 `verdict: PASS` 表示审查通过。
 
@@ -43,16 +42,16 @@ metadata:
 ### Step 1: 审查代码
 
 读取以下内容：
-- `$W/plan_res.md` — 每个组件的预期
-- `$W/survey_res.md` — 核心公式
-- `$W/project/` — 实际代码
-- `$W/ml_res.md` — 执行结果
+- `plan_res.md` — 每个组件的预期
+- `survey_res.md` — 核心公式
+- `project/` — 实际代码
+- `ml_res.md` — 执行结果
 
 ### Step 2: 提取原子性概念清单
 
 **⚠️ 这是 Novix Judge Agent 的核心机制 — 逐一核对每个原子性学术概念。**
 
-从 `$W/survey_res.md` 的"关键公式汇总"和"核心方法对比"中，提取所有需要在代码中实现的**原子性学术概念**（每个公式、每个核心组件都是一个概念）。
+从 `survey_res.md` 的"关键公式汇总"和"核心方法对比"中，提取所有需要在代码中实现的**原子性学术概念**（每个公式、每个核心组件都是一个概念）。
 
 为每个概念记录：
 - 概念名称（如 "Multi-Head Attention", "Contrastive Loss", "Batch Normalization"）
@@ -123,7 +122,7 @@ metadata:
 
 ### Step 4: 写入审查报告
 
-写入 `$W/iterations/judge_v1.md`：
+写入 `iterations/judge_v1.md`：
 
 ```markdown
 # Review v1
@@ -201,14 +200,14 @@ metadata:
 循环最多 3 次：
 
 1. 读取 `judge_v{N}.md` 的修改建议
-2. **防偏移检查：重新读取** `$W/survey_res.md` 和 `$W/plan_res.md`
+2. **防偏移检查：重新读取** `survey_res.md` 和 `plan_res.md`
    - 对照原始学术设计目标
    - 确保修改不是为了"绕过审查"而偏离学术严谨性
    - 确认修改符合 survey 中的公式定义和 plan 中的设计意图
-3. 修改 `$W/project/` 中的代码（修复 bug、补全缺失实现）
+3. 修改 `project/` 中的代码（修复 bug、补全缺失实现）
 4. 重新执行：
    ```bash
-   cd $W/project && source .venv/bin/activate && python3 run.py --epochs 2
+   cd project && source .venv/bin/activate && python3 run.py --epochs 2
    ```
 5. 读取执行输出，验证修复
 6. **重新执行 Step 2-4**（提取概念清单 → 逐项检查 → 写报告），写入 `judge_v{N+1}.md`
@@ -225,10 +224,10 @@ metadata:
 #### 5b.1 性能诊断
 
 重新读取以下材料进行诊断：
-- `$W/ml_res.md` — 2 epoch 验证的具体数值
-- `$W/survey_res.md` — baseline 方法的超参数设置（特别是学习率、batch size）
-- `$W/plan_res.md` — 当前实现的超参数配置
-- `$W/project/run.py` 和 `$W/project/training/` — 训练配置代码
+- `ml_res.md` — 2 epoch 验证的具体数值
+- `survey_res.md` — baseline 方法的超参数设置（特别是学习率、batch size）
+- `plan_res.md` — 当前实现的超参数配置
+- `project/run.py` 和 `project/training/` — 训练配置代码
 
 **诊断检查清单**：
 
@@ -255,11 +254,11 @@ metadata:
 1. **调整学习率**（优先级：高，预期改善：显著）
    - **当前值**: lr=1e-5 (from plan_res.md)
    - **建议值**: lr=1e-3 (from survey_res.md Table 2, all baselines use 1e-3)
-   - **修改位置**: `$W/project/run.py:L15` — `optimizer = Adam(lr=1e-3)`
+   - **修改位置**: `project/run.py:L15` — `optimizer = Adam(lr=1e-3)`
    - **理由**: Loss 下降仅 0.9%，远低于正常 10%+，高度怀疑 lr 过小
 
 2. **添加数据归一化**（优先级：中，预期改善：中等）
-   - **检查**: `$W/project/data/dataset.py` 是否有归一化
+   - **检查**: `project/data/dataset.py` 是否有归一化
    - **建议**: 添加 `transforms.Normalize(mean=[0.5], std=[0.5])`
    - **理由**: 如果输入数据范围 [0,255]，模型收敛会很慢
 ```
@@ -269,7 +268,7 @@ metadata:
 1. 根据建议**逐项尝试**（从优先级高的开始）
 2. 每次修改后：
    ```bash
-   cd $W/project && source .venv/bin/activate && python3 run.py --epochs 2
+   cd project && source .venv/bin/activate && python3 run.py --epochs 2
    ```
 3. 读取新的执行输出，对比改进前后：
    - Loss reduction 是否提升？（如 0.9% → 12%）

package/skills/research-survey/SKILL.md

@@ -14,29 +14,22 @@ metadata:
 
 **Don't ask permission. Just do it.**
 
-**Workspace:** `$W` = working directory provided in task parameter.
-
 ## Prerequisites
 
 Read and verify these files exist before starting:
 
 | File | Source |
 |------|--------|
-| `$W/papers/_meta/*.json` | /research-collect |
-| `$W/papers/_downloads/` or `$W/papers/{direction}/` | /research-collect |
-| `$W/repos/` | /research-collect Phase 3 |
-| `$W/prepare_res.md` | /research-collect Phase 3 |
+| `papers/` | /research-collect 或 /metabolism |
 
 **If papers are missing, STOP:** "需要先运行 /research-collect 完成论文下载"
 
-**Note:** 如果 `prepare_res.md` 中注明"无可用参考仓库"，代码映射步骤可跳过，但需在 survey_res.md 中标注。
-
 ## Output
 
 | File | Content |
 |------|---------|
-| `$W/notes/paper_{arxiv_id}.md` | Per-paper structured notes |
-| `$W/survey_res.md` | Synthesis report |
+| `knowledge/paper_{id}.md` | Per-paper structured notes with frontmatter, formulas, and code mapping |
+| `survey_res.md` | Synthesis report with method comparison, scope boundary, and concrete next-step suggestions |
 
 ---
 
@@ -45,30 +38,23 @@ Read and verify these files exist before starting:
 ### Step 1: 收集论文列表
 
 ```bash
-ls $W/papers/_meta/
+ls papers/
 ```
 
-读取所有 `.json` 元数据，构建论文列表。按 score 降序排列。
+列出所有论文目录（arXiv 源文件）和 PDF 文件。
 
 ### Step 2: 逐篇深度分析
 
-**对每篇论文**（优先高分论文）：
+**对每篇论文：**
 
 #### 2.1 读 .tex 源码
 
-找到论文的 .tex 文件（在 `_downloads/{arxiv_id}/` 或 `{direction}/{arxiv_id}/` 下），重点读取：
+找到论文的 .tex 文件（在 `papers/{arxiv_id}/` 下），重点读取：
 - **Method / Approach** section
 - **Model Architecture** section
 - 数学公式定义
 
-**对于大型论文**（>2000 行），使用 `paper_browser` 分页阅读：
-```javascript
-// 先读前 100 行找到 section 位置
-paper_browser({ file_path: "$W/papers/{arxiv_id}/{file}.tex", start_line: 1, num_lines: 100 })
-
-// 找到 Method section 后，跳转到该位置
-paper_browser({ file_path: "$W/papers/{arxiv_id}/{file}.tex", start_line: 450, num_lines: 150 })
-```
+**对于大型论文**（>2000 行），分段读取关键 section，避免上下文溢出。
 
 如果没有 .tex（只有 PDF），基于 abstract 分析。
 
@@ -83,16 +69,25 @@ paper_browser({ file_path: "$W/papers/{arxiv_id}/{file}.tex", start_line: 450, n
 
 **⚠️ 强制性步骤（当 repos/ 存在时）** — 代码映射是下游 plan 和 implement 的关键输入。
 
-读取 `$W/prepare_res.md` 中的仓库列表，对每个公式/核心概念：
+读取 `prepare_res.md` 中的仓库列表，对每个公式/核心概念：
 1. 在对应仓库中搜索实现代码（用 grep 关键类名/函数名）
 2. 记录**文件路径、行号、代码片段**
 3. 如果多个仓库有不同实现，记录差异
 
 #### 2.4 写入笔记
 
-写入 `$W/notes/paper_{arxiv_id}.md`：
+写入 `knowledge/paper_{id}.md`：
 
 ```markdown
+---
+paper_id: "{arxiv_id}"
+title: "{Paper Title}"
+evidence_level: "full_text"
+method_family: "{method family}"
+key_formula_count: 1
+code_mapping_count: 1
+---
+
 # {Paper Title}
 
 - **arXiv:** {arxiv_id}
@@ -120,7 +115,7 @@ $$
 
 ### Step 3: 综合报告
 
-读取所有 `notes/paper_*.md`，写入 `$W/survey_res.md`：
+读取所有 `knowledge/paper_*.md`，写入 `survey_res.md`：
 
 ```markdown
 # Survey Synthesis
@@ -135,6 +130,12 @@ $$
 |------|------|----------|--------|------|
 | ... | ... | ... | ... | ... |
 
+## Scope Boundary
+
+- Preconditions: {what conditions this method relies on}
+- Not recommended when: {where this method should not be directly applied}
+- Evidence strength: {full text / PDF / metadata}
+
 ## 技术路线建议
 
 基于以上分析，推荐的技术路线是：
@@ -165,3 +166,5 @@ $$
 2. 每篇笔记必须包含至少 1 个数学公式
 3. 如果有 repos/，必须尝试找到公式到代码的映射
 4. survey_res.md 必须包含方法对比表
+5. survey_res.md must include a scope-boundary section and concrete guidance for the current project
+6. Before writing the final synthesis, write at least 2 real paper notes to disk

package/skills/write-paper/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: write-paper
+description: "Use this when the user wants a systems paper, experiment paper, technical report, or extended abstract drafted from existing Scientify artifacts. Builds a claim-bounded paper draft from experiment outputs, figures, and supporting notes."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "📄",
+      },
+  }
+---
+
+# Paper Writing
+
+**Don't ask permission. Just do it.**
+
+Use this skill for experiment-driven or systems-style papers.
+
+**Do not use this for pure survey writing.** For literature reviews or thesis review chapters, use `/write-review-paper` instead.
+
+Outputs go to `paper/`.
+
+## Prerequisites
+
+You need a real evidence base from existing artifacts, ideally:
+
+- `experiment_res.md`
+- one or more figure files
+- one or more comparison tables / result summaries
+- optional support from `survey_res.md`, `plan_res.md`, `ml_res.md`
+
+If the evidence base is too thin, write the draft conservatively and mark unsupported sections as `TODO`.
+
+## Required Outputs
+
+- `paper/claim_inventory.md`
+- `paper/figures_manifest.md`
+- `paper/draft.md`
+- `paper/manuscript.tex`
+- `paper/sections/*.tex`
+- `paper/references.bib`
+- `paper/build_paper.sh`
+- `paper/build/build.log`
+- `paper/build/manuscript.pdf` when the build succeeds
+- `paper/build/build_errors.md` when the build fails
+
+## Optional Supporting Outputs
+
+- `paper/boundary_notes.md`
+- venue- or artifact-specific optional sections such as:
+  - `paper/sections/ablations.tex`
+  - `paper/sections/discussion_scope.tex`
+  - `paper/sections/related_work.tex`
+
+## Workflow
+
+### Step 1: Build the Claim Inventory
+
+Before drafting prose, create `claim_inventory.md`.
+
+Each claim entry must use the same fixed fields:
+
+- `claim_id`
+- `claim_text`
+- `claim_type` (`result`, `observation`, or `interpretation`)
+- `source_files`
+- `figure_or_table_anchor`
+- `baseline`
+- `protocol_or_guardrail`
+- `evidence_type` (`simulator`, `local_runtime`, or `runtime`)
+- `confidence` (`high`, `medium`, or `low`)
+- `allowed_in_sections` (`abstract`, `intro`, `results`, `discussion`, `conclusion`, `boundary_note`)
+
+Use `references/evidence-contract.md` and `references/claim-inventory-template.md`.
+
+### Step 2: Build the Figures Manifest
+
+Create `figures_manifest.md` as the shared contract for claim support, prose callouts, captions, and LaTeX figure blocks.
+
+Each figure entry must include:
+
+- `figure_id`
+- `file_path`
+- `latex_label`
+- `section`
+- `placement_hint`
+- `caption_short`
+- `caption_long`
+- `takeaway_sentence`
+- `callout_sentence`
+- `baseline`
+- `evidence_type`
+- `source_metrics`
+- `source_files`
+- `supports_claim_ids`
+- `must_appear_before_claim_ids`
+
+Use:
+
+- `references/figures-manifest-template.md`
+- `references/figure-callout-template.md`
+
+Treat this manifest as the single source of truth for:
+
+- which claim a figure supports
+- where the figure belongs in the paper
+- what the first text callout should say
+- what goes into the short and long caption
+- what the eventual LaTeX block should render
+
+If a result is intentionally table-only or text-only evidence, say that explicitly in the relevant results paragraph instead of inventing a figure placeholder.
+
+### Step 3: Draft the Paper
+
+Write `draft.md` using:
+
+- `references/paper-template.md`
+- `references/paragraph-contract.md`
+- `references/style-banlist.md`
+- `references/paragraph-examples.md`
+
+Then populate the LaTeX starter bundle under `paper/`:
+
+- update `paper/manuscript.tex`
+- fill the core sections under `paper/sections/*.tex`
+- add optional sections only when they materially help the current paper
+- keep `paper/references.bib` aligned with the draft when citations are ready
+- make `paper/sections/main_results.tex` consistent with `paper/figures_manifest.md`
+
+Treat the manuscript as a composable section set, not a fixed checklist. The default core path is:
+
+- `abstract`
+- `introduction`
+- `problem_setup`
+- `method_system`
+- `experimental_protocol`
+- `main_results`
+- `conclusion`
+
+Optional modules should be chosen based on venue, evidence profile, and paper shape:
+
+- `ablations`
+- `discussion_scope`
+- `related_work`
+
+Choose a paper shape before filling sections:
+
+- `result_note`
+  - use the core path only
+  - keep boundary handling in `main_results`, `conclusion`, or `paper/boundary_notes.md`
+- `systems_full`
+  - use the core path plus whichever optional modules materially help
+  - add `discussion_scope` only when interpretation and evidence boundary need a dedicated home
+- `artifact_summary`
+  - keep the structure lean and evidence-first
+  - prefer short results plus a compact conclusion boundary note over extra sections
+- `workshop_short`
+  - compress setup and method aggressively
+  - avoid optional sections unless they carry real argumentative weight
+
+Every result paragraph must stay within the claim inventory. If the evidence only supports a narrower claim, write the narrower claim.
+
+Use this section contract while drafting:
+
+- `Abstract` may only use claims with `confidence=high`.
+- `Introduction` may use problem framing and setup claims, but must not introduce new result claims.
+- `Results` must anchor each substantive paragraph to at least one `claim_id`.
+- `Discussion` may interpret results, but interpretation must remain explicitly separated from observed outcomes.
+- `Boundary and caveat handling` must explicitly cover evidence boundaries, missing validations, and unsupported comparisons somewhere in the paper.
+- `Future Work` is the only place where unsupported but plausible ideas may appear.
+
+Use the figures manifest as a hard drafting contract:
+
+- every headline result claim must map to at least one `supports_claim_ids` entry in `paper/figures_manifest.md`, unless the paragraph explicitly states that the evidence is table-only or text-only
+- the first prose mention of a figure must use or closely follow its `callout_sentence`
+- a figure callout must appear before the figure block or at the first figure discussion point
+- `caption_short`, `caption_long`, `latex_label`, `file_path`, and `placement_hint` must stay aligned with the eventual LaTeX figure block
+- if a claim needs figure support but no manifest entry names it in `supports_claim_ids`, do not treat that claim as ready for the main results section
+
+Use these paragraph-level rules:
+
+- Every results paragraph must contain at least one quantitative statement.
+- Every comparison sentence must explicitly name a baseline or comparison target.
+- Every interpretation sentence must be clearly distinguishable from the observed evidence it builds on.
+- Avoid adjective inflation when a metric, baseline, or evidence path would be more precise.
+- If a paragraph only restates a figure without adding a takeaway or boundary, rewrite it.
+
+### Stop Conditions
+
+Do not continue into a full results draft if any of the following is true:
+
+- `experiment_res.md` is missing and no equivalent result artifact exists.
+- No figure or table anchor exists for a headline result.
+- A claimed improvement has no explicit baseline.
+- A result claim has no source file or no protocol / guardrail.
+- `paper/figures_manifest.md` is missing for a figure-backed results section.
+- a required figure entry is missing `section`, `placement_hint`, `callout_sentence`, or `supports_claim_ids`
+
+If one of these conditions is triggered, stop after writing `claim_inventory.md` and a boundary/caveat note, and mark the blocked sections in `draft.md` as `TODO`.
+
+Do not write a results paragraph if:
+
+- it cannot be tied to a `claim_id`
+- it has no quantitative statement
+- it makes a comparison without naming a baseline
+- it implicitly depends on a figure but the manifest does not specify the figure contract
+
+### Step 4: Choose the Boundary Surface
+
+Do not treat `Limitations` as a default section.
+
+Choose the lightest surface that still makes the evidence boundary explicit:
+
+- a dedicated `discussion_scope` section
+- a short boundary paragraph in `Conclusion`
+- a short caveat paragraph in `Main Results`
+- a standalone `paper/boundary_notes.md` during drafting
+
+Use a dedicated limitations section only when the venue, review criteria, or artifact risk explicitly requires it.
+
+If you need a drafting aid, use `references/boundary-notes-template.md`.
+
+### Step 5: Build the PDF
+
+Run `bash paper/build_paper.sh`.
+
+The build chain should:
+
+- write compiler output to `paper/build/build.log`
+- produce `paper/build/manuscript.pdf` when successful
+- write `paper/build/build_errors.md` when the build fails or when `tectonic` is unavailable
+
+### Step 6: Hand Off to the Release Gate
+
+Do not treat the manuscript as ready to share immediately after the PDF build succeeds.
+
+Before external sharing, run `/artifact-review` so the workspace also has:
+
+- `review/artifact_review.md`
+- `review/release_checklist.md`
+- `review/release_gate.json`
+
+Treat release readiness as unverified until the release gate is fresh and not `HOLD`.
+
+## Writing Rules
+
+1. No headline metric without baseline + protocol + source path.
+2. No simulator-only result should be phrased as runtime validation.
+3. Distinguish observed result from interpretation.
+4. Keep unsupported ideas in a clearly marked future-work section, not in the main results.
+5. Do not place a claim in a section that is not listed in its `allowed_in_sections`.
+6. Do not use empty praise words where a metric, baseline, or scope boundary should appear.

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

@@ -0,0 +1,34 @@
+# Boundary Notes Template
+
+Use this template when a dedicated `Limitations` section is too heavy or too venue-specific.
+
+You can surface these notes in any of the following places:
+
+- a short `Discussion / Scope Note` section
+- a caveat paragraph at the end of `Main Results`
+- a boundary paragraph in `Conclusion`
+- a standalone drafting file such as `paper/boundary_notes.md`
+
+Suggested structure:
+
+```md
+# Boundary Notes
+
+## Supported Today
+- State the strongest supported claim.
+
+## Not Claimed
+- State the stronger claim that is intentionally not made.
+
+## Evidence Boundary
+- Name whether the evidence is simulator, local runtime, or runtime.
+
+## Validation Gaps
+- List the smallest missing validations that prevent stronger wording.
+```
+
+Writing rules:
+
+- Keep this concrete and artifact-specific.
+- Prefer a short, sharp boundary note over a generic limitations section.
+- If the manuscript already has a natural home for caveats, fold these points there instead of forcing a dedicated section.

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

@@ -0,0 +1,32 @@
+# Claim Inventory Template
+
+Use this structure for `paper/claim_inventory.md` before drafting any prose:
+
+```yaml
+- claim_id: "claim-001"
+  claim_text: "KV2 achieves 17.53% mean TTFT gain vs INT4-FIFO under the stated simulator protocol."
+  claim_type: "result"
+  source_files:
+    - "experiment_res.md"
+    - "Comparision-KV2/results/kv2_compare_quant_family_local_20260329.json"
+  figure_or_table_anchor: "fig-kv2-tradeoff-overview"
+  baseline: "INT4-FIFO"
+  protocol_or_guardrail: "quality_penalty_mean <= 0.02"
+  evidence_type: "simulator"
+  confidence: "high"
+  allowed_in_sections:
+    - "abstract"
+    - "results"
+    - "discussion"
+    - "conclusion"
+    - "boundary_note"
+```
+
+Authoring notes:
+
+- Use one claim entry per independently reviewable statement.
+- Use `claim_type=result` for measured outcomes.
+- Use `claim_type=observation` for descriptive trends that stop short of causal interpretation.
+- Use `claim_type=interpretation` for explanation or hypothesis, and keep these out of `abstract` unless independently supported.
+- `allowed_in_sections` is a hard constraint, not a suggestion.
+- If a field is unknown, stop and resolve the evidence gap instead of drafting around it.

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

@@ -0,0 +1,57 @@
+# Evidence Contract
+
+Every headline claim should be recorded using this structure before drafting prose:
+
+```yaml
+- claim_id: "claim-001"
+  claim_text: "KV2 achieves 17.53% mean TTFT gain vs INT4-FIFO under the stated simulator protocol."
+  claim_type: "result"
+  source_files:
+    - "Comparision-KV2/results/kv2_compare_quant_family_local_20260329.json"
+    - "experiment_res.md"
+  figure_or_table_anchor: "fig-kv2-tradeoff-overview"
+  baseline: "INT4-FIFO"
+  evidence_type: "simulator"
+  protocol_or_guardrail: "quality_penalty_mean <= 0.02"
+  confidence: "high"
+  allowed_in_sections:
+    - "abstract"
+    - "results"
+    - "discussion"
+    - "conclusion"
+    - "boundary_note"
+```
+
+Required fields:
+
+- `claim_id`
+- `claim_text`
+- `claim_type`
+- `source_files`
+- `figure_or_table_anchor`
+- `baseline`
+- `evidence_type`
+- `protocol_or_guardrail`
+- `confidence`
+- `allowed_in_sections`
+
+Field notes:
+
+- `claim_id` must be stable within the draft and reused by review findings.
+- `claim_type` must be one of `result`, `observation`, or `interpretation`.
+- `source_files` should list every artifact needed to verify the claim.
+- `figure_or_table_anchor` should point to the figure/table label used in the draft or manifest.
+- `confidence` should be `high`, `medium`, or `low`.
+- `allowed_in_sections` defines where the claim may appear in prose. Do not place the claim outside this list.
+
+Allowed `evidence_type` values:
+
+- `simulator`
+- `local_runtime`
+- `runtime`
+
+Minimum writing gate:
+
+- Do not draft a headline result if `baseline`, `protocol_or_guardrail`, or `source_files` is missing.
+- Do not place a claim in `abstract` unless `confidence` is `high`.
+- Do not write simulator-only evidence as runtime validation.

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

@@ -0,0 +1,38 @@
+# Figure Callout Template
+
+Use this guide when writing the first prose mention of a figure.
+
+The callout sentence should do three jobs:
+
+1. name the figure
+2. state the concrete takeaway
+3. name the comparison target or evaluation frame when that is central to the claim
+
+Preferred structure:
+
+```text
+Figure \ref{{latex_label}} shows {takeaway_sentence} under {protocol or evaluation frame}.
+```
+
+Examples:
+
+```text
+Figure \ref{fig:kv2-tradeoff-overview} shows that KV2 improves TTFT relative to INT4-FIFO under the shared simulator protocol.
+```
+
+```text
+Figure \ref{fig:runtime-smoke} shows that the local runtime smoke test preserves the winner ordering observed in the simulator summary.
+```
+
+Avoid callouts that only announce the figure:
+
+```text
+Figure 3 shows the results.
+```
+
+Good callouts should:
+
+- appear before the figure block or at the first discussion point
+- contain the main takeaway, not just a pointer
+- stay consistent with `caption_long`
+- avoid introducing a stronger claim than the figure actually supports