scientify 3.0.0 → 3.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.en.md +21 -1
  2. package/README.md +27 -0
  3. package/dist/index.js +1 -1
  4. package/dist/index.js.map +1 -1
  5. package/dist/src/cli/research.d.ts.map +1 -1
  6. package/dist/src/cli/research.js +42 -1
  7. package/dist/src/cli/research.js.map +1 -1
  8. package/dist/src/commands.d.ts.map +1 -1
  9. package/dist/src/commands.js +159 -1
  10. package/dist/src/commands.js.map +1 -1
  11. package/dist/src/release-gate.d.ts +14 -0
  12. package/dist/src/release-gate.d.ts.map +1 -0
  13. package/dist/src/release-gate.js +124 -0
  14. package/dist/src/release-gate.js.map +1 -0
  15. package/dist/src/templates/bootstrap.d.ts.map +1 -1
  16. package/dist/src/templates/bootstrap.js +139 -62
  17. package/dist/src/templates/bootstrap.js.map +1 -1
  18. package/openclaw.plugin.json +8 -1
  19. package/package.json +1 -1
  20. package/skills/algorithm-selection/SKILL.md +103 -0
  21. package/skills/algorithm-selection/references/candidate-template.md +13 -0
  22. package/skills/algorithm-selection/references/selection-template.md +39 -0
  23. package/skills/artifact-review/SKILL.md +146 -0
  24. package/skills/artifact-review/references/release-gate-template.md +40 -0
  25. package/skills/artifact-review/references/review-checklist.md +45 -0
  26. package/skills/artifact-review/references/style-review-checklist.md +30 -0
  27. package/skills/baseline-runner/SKILL.md +103 -0
  28. package/skills/baseline-runner/references/baseline-matrix-template.md +9 -0
  29. package/skills/baseline-runner/references/baseline-report-template.md +25 -0
  30. package/skills/dataset-validate/SKILL.md +104 -0
  31. package/skills/dataset-validate/references/data-validation-template.md +38 -0
  32. package/skills/figure-standardize/SKILL.md +110 -0
  33. package/skills/figure-standardize/references/caption-template.md +12 -0
  34. package/skills/figure-standardize/references/figure-placement-template.md +30 -0
  35. package/skills/figure-standardize/references/figure-style-guide.md +36 -0
  36. package/skills/release-layout/SKILL.md +73 -0
  37. package/skills/release-layout/references/page-structure.md +14 -0
  38. package/skills/research-experiment/SKILL.md +10 -1
  39. package/skills/research-survey/SKILL.md +19 -2
  40. package/skills/write-paper/SKILL.md +252 -0
  41. package/skills/write-paper/references/boundary-notes-template.md +34 -0
  42. package/skills/write-paper/references/claim-inventory-template.md +32 -0
  43. package/skills/write-paper/references/evidence-contract.md +57 -0
  44. package/skills/write-paper/references/figure-callout-template.md +38 -0
  45. package/skills/write-paper/references/figures-manifest-template.md +44 -0
  46. package/skills/write-paper/references/latex/README.md +22 -0
  47. package/skills/write-paper/references/latex/build_paper.sh +41 -0
  48. package/skills/write-paper/references/latex/manuscript.tex +39 -0
  49. package/skills/write-paper/references/latex/references.bib +10 -0
  50. package/skills/write-paper/references/latex/sections/ablations.tex +3 -0
  51. package/skills/write-paper/references/latex/sections/abstract.tex +3 -0
  52. package/skills/write-paper/references/latex/sections/conclusion.tex +3 -0
  53. package/skills/write-paper/references/latex/sections/discussion_scope.tex +7 -0
  54. package/skills/write-paper/references/latex/sections/experimental_protocol.tex +3 -0
  55. package/skills/write-paper/references/latex/sections/introduction.tex +3 -0
  56. package/skills/write-paper/references/latex/sections/main_results.tex +9 -0
  57. package/skills/write-paper/references/latex/sections/method_system.tex +3 -0
  58. package/skills/write-paper/references/latex/sections/problem_setup.tex +3 -0
  59. package/skills/write-paper/references/latex/sections/related_work.tex +3 -0
  60. package/skills/write-paper/references/paper-template.md +155 -0
  61. package/skills/write-paper/references/paragraph-contract.md +139 -0
  62. package/skills/write-paper/references/paragraph-examples.md +171 -0
  63. package/skills/write-paper/references/style-banlist.md +81 -0
  64. package/skills/write-review-paper/SKILL.md +10 -4
@@ -30,7 +30,7 @@ metadata:
30
30
 
31
31
  | File | Content |
32
32
  |------|---------|
33
- | `experiment_res.md` | 完整实验报告(含 full training + 消融 + 补充实验) |
33
+ | `experiment_res.md` | Full experiment report (full training, ablations, supplementary experiments) with explicit headline metrics, baselines, guardrails, and figure anchors |
34
34
  | `experiment_analysis/analysis_{N}.md` | 每轮实验分析报告(迭代过程中产生) |
35
35
 
36
36
  ---
@@ -128,6 +128,9 @@ python3 run.py --experiment {exp_name}
128
128
  - [RESULT] val_metric={value}
129
129
  - [RESULT] elapsed={value}
130
130
  - [RESULT] device={device}
131
+ - [METRIC] name={headline_metric} value={value} unit={unit} baseline={baseline}
132
+ - [GUARD] name={guard_name} value={value} threshold={threshold} pass={true/false}
133
+ - [FIGURE] file={figure path}
131
134
 
132
135
  > 以上数值来自真实执行输出。
133
136
 
@@ -156,6 +159,11 @@ python3 run.py --experiment {exp_name}
156
159
  | Ours | {value} | — |
157
160
  | {Baseline} | {value} | ... |
158
161
 
162
+ ## Scope / Evidence Boundary
163
+ - baseline: {which baseline is used}
164
+ - protocol / guardrail: {evaluation rule}
165
+ - evidence_type: {simulator / local_runtime / full_runtime}
166
+
159
167
  ### Visualizations
160
168
  - 训练曲线: `project/figures/training_curve.png`
161
169
  - {其他可视化}: `project/figures/{name}.png`
@@ -177,3 +185,4 @@ python3 run.py --experiment {exp_name}
177
185
  4. 如果 full training 失败(OOM 等),调整 batch_size 后重试,不要跳过
178
186
  5. **补充实验迭代必须做 2 轮(Novix Exp Analyzer 机制)** — 第 1 轮针对初始结果,第 2 轮针对补充实验结果
179
187
  6. 补充实验不改核心算法,只改实验配置/参数/可视化代码
188
+ 7. Every headline metric must include a baseline, and every main conclusion must point back to real outputs or figure files
@@ -28,8 +28,8 @@ Read and verify these files exist before starting:
28
28
 
29
29
  | File | Content |
30
30
  |------|---------|
31
- | `knowledge/paper_{id}.md` | Per-paper structured notes |
32
- | `survey_res.md` | Synthesis report |
31
+ | `knowledge/paper_{id}.md` | Per-paper structured notes with frontmatter, formulas, and code mapping |
32
+ | `survey_res.md` | Synthesis report with method comparison, scope boundary, and concrete next-step suggestions |
33
33
 
34
34
  ---
35
35
 
@@ -79,6 +79,15 @@ ls papers/
79
79
  写入 `knowledge/paper_{id}.md`:
80
80
 
81
81
  ```markdown
82
+ ---
83
+ paper_id: "{arxiv_id}"
84
+ title: "{Paper Title}"
85
+ evidence_level: "full_text"
86
+ method_family: "{method family}"
87
+ key_formula_count: 1
88
+ code_mapping_count: 1
89
+ ---
90
+
82
91
  # {Paper Title}
83
92
 
84
93
  - **arXiv:** {arxiv_id}
@@ -121,6 +130,12 @@ $$
121
130
  |------|------|----------|--------|------|
122
131
  | ... | ... | ... | ... | ... |
123
132
 
133
+ ## Scope Boundary
134
+
135
+ - Preconditions: {what conditions this method relies on}
136
+ - Not recommended when: {where this method should not be directly applied}
137
+ - Evidence strength: {full text / PDF / metadata}
138
+
124
139
  ## 技术路线建议
125
140
 
126
141
  基于以上分析,推荐的技术路线是:
@@ -151,3 +166,5 @@ $$
151
166
  2. 每篇笔记必须包含至少 1 个数学公式
152
167
  3. 如果有 repos/,必须尝试找到公式到代码的映射
153
168
  4. survey_res.md 必须包含方法对比表
169
+ 5. survey_res.md must include a scope-boundary section and concrete guidance for the current project
170
+ 6. Before writing the final synthesis, write at least 2 real paper notes to disk
@@ -0,0 +1,252 @@
1
+ ---
2
+ name: write-paper
3
+ 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."
4
+ metadata:
5
+ {
6
+ "openclaw":
7
+ {
8
+ "emoji": "📄",
9
+ },
10
+ }
11
+ ---
12
+
13
+ # Paper Writing
14
+
15
+ **Don't ask permission. Just do it.**
16
+
17
+ Use this skill for experiment-driven or systems-style papers.
18
+
19
+ **Do not use this for pure survey writing.** For literature reviews or thesis review chapters, use `/write-review-paper` instead.
20
+
21
+ Outputs go to `paper/`.
22
+
23
+ ## Prerequisites
24
+
25
+ You need a real evidence base from existing artifacts, ideally:
26
+
27
+ - `experiment_res.md`
28
+ - one or more figure files
29
+ - one or more comparison tables / result summaries
30
+ - optional support from `survey_res.md`, `plan_res.md`, `ml_res.md`
31
+
32
+ If the evidence base is too thin, write the draft conservatively and mark unsupported sections as `TODO`.
33
+
34
+ ## Required Outputs
35
+
36
+ - `paper/claim_inventory.md`
37
+ - `paper/figures_manifest.md`
38
+ - `paper/draft.md`
39
+ - `paper/manuscript.tex`
40
+ - `paper/sections/*.tex`
41
+ - `paper/references.bib`
42
+ - `paper/build_paper.sh`
43
+ - `paper/build/build.log`
44
+ - `paper/build/manuscript.pdf` when the build succeeds
45
+ - `paper/build/build_errors.md` when the build fails
46
+
47
+ ## Optional Supporting Outputs
48
+
49
+ - `paper/boundary_notes.md`
50
+ - venue- or artifact-specific optional sections such as:
51
+ - `paper/sections/ablations.tex`
52
+ - `paper/sections/discussion_scope.tex`
53
+ - `paper/sections/related_work.tex`
54
+
55
+ ## Workflow
56
+
57
+ ### Step 1: Build the Claim Inventory
58
+
59
+ Before drafting prose, create `claim_inventory.md`.
60
+
61
+ Each claim entry must use the same fixed fields:
62
+
63
+ - `claim_id`
64
+ - `claim_text`
65
+ - `claim_type` (`result`, `observation`, or `interpretation`)
66
+ - `source_files`
67
+ - `figure_or_table_anchor`
68
+ - `baseline`
69
+ - `protocol_or_guardrail`
70
+ - `evidence_type` (`simulator`, `local_runtime`, or `runtime`)
71
+ - `confidence` (`high`, `medium`, or `low`)
72
+ - `allowed_in_sections` (`abstract`, `intro`, `results`, `discussion`, `conclusion`, `boundary_note`)
73
+
74
+ Use `references/evidence-contract.md` and `references/claim-inventory-template.md`.
75
+
76
+ ### Step 2: Build the Figures Manifest
77
+
78
+ Create `figures_manifest.md` as the shared contract for claim support, prose callouts, captions, and LaTeX figure blocks.
79
+
80
+ Each figure entry must include:
81
+
82
+ - `figure_id`
83
+ - `file_path`
84
+ - `latex_label`
85
+ - `section`
86
+ - `placement_hint`
87
+ - `caption_short`
88
+ - `caption_long`
89
+ - `takeaway_sentence`
90
+ - `callout_sentence`
91
+ - `baseline`
92
+ - `evidence_type`
93
+ - `source_metrics`
94
+ - `source_files`
95
+ - `supports_claim_ids`
96
+ - `must_appear_before_claim_ids`
97
+
98
+ Use:
99
+
100
+ - `references/figures-manifest-template.md`
101
+ - `references/figure-callout-template.md`
102
+
103
+ Treat this manifest as the single source of truth for:
104
+
105
+ - which claim a figure supports
106
+ - where the figure belongs in the paper
107
+ - what the first text callout should say
108
+ - what goes into the short and long caption
109
+ - what the eventual LaTeX block should render
110
+
111
+ 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.
112
+
113
+ ### Step 3: Draft the Paper
114
+
115
+ Write `draft.md` using:
116
+
117
+ - `references/paper-template.md`
118
+ - `references/paragraph-contract.md`
119
+ - `references/style-banlist.md`
120
+ - `references/paragraph-examples.md`
121
+
122
+ Then populate the LaTeX starter bundle under `paper/`:
123
+
124
+ - update `paper/manuscript.tex`
125
+ - fill the core sections under `paper/sections/*.tex`
126
+ - add optional sections only when they materially help the current paper
127
+ - keep `paper/references.bib` aligned with the draft when citations are ready
128
+ - make `paper/sections/main_results.tex` consistent with `paper/figures_manifest.md`
129
+
130
+ Treat the manuscript as a composable section set, not a fixed checklist. The default core path is:
131
+
132
+ - `abstract`
133
+ - `introduction`
134
+ - `problem_setup`
135
+ - `method_system`
136
+ - `experimental_protocol`
137
+ - `main_results`
138
+ - `conclusion`
139
+
140
+ Optional modules should be chosen based on venue, evidence profile, and paper shape:
141
+
142
+ - `ablations`
143
+ - `discussion_scope`
144
+ - `related_work`
145
+
146
+ Choose a paper shape before filling sections:
147
+
148
+ - `result_note`
149
+ - use the core path only
150
+ - keep boundary handling in `main_results`, `conclusion`, or `paper/boundary_notes.md`
151
+ - `systems_full`
152
+ - use the core path plus whichever optional modules materially help
153
+ - add `discussion_scope` only when interpretation and evidence boundary need a dedicated home
154
+ - `artifact_summary`
155
+ - keep the structure lean and evidence-first
156
+ - prefer short results plus a compact conclusion boundary note over extra sections
157
+ - `workshop_short`
158
+ - compress setup and method aggressively
159
+ - avoid optional sections unless they carry real argumentative weight
160
+
161
+ Every result paragraph must stay within the claim inventory. If the evidence only supports a narrower claim, write the narrower claim.
162
+
163
+ Use this section contract while drafting:
164
+
165
+ - `Abstract` may only use claims with `confidence=high`.
166
+ - `Introduction` may use problem framing and setup claims, but must not introduce new result claims.
167
+ - `Results` must anchor each substantive paragraph to at least one `claim_id`.
168
+ - `Discussion` may interpret results, but interpretation must remain explicitly separated from observed outcomes.
169
+ - `Boundary and caveat handling` must explicitly cover evidence boundaries, missing validations, and unsupported comparisons somewhere in the paper.
170
+ - `Future Work` is the only place where unsupported but plausible ideas may appear.
171
+
172
+ Use the figures manifest as a hard drafting contract:
173
+
174
+ - 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
175
+ - the first prose mention of a figure must use or closely follow its `callout_sentence`
176
+ - a figure callout must appear before the figure block or at the first figure discussion point
177
+ - `caption_short`, `caption_long`, `latex_label`, `file_path`, and `placement_hint` must stay aligned with the eventual LaTeX figure block
178
+ - 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
179
+
180
+ Use these paragraph-level rules:
181
+
182
+ - Every results paragraph must contain at least one quantitative statement.
183
+ - Every comparison sentence must explicitly name a baseline or comparison target.
184
+ - Every interpretation sentence must be clearly distinguishable from the observed evidence it builds on.
185
+ - Avoid adjective inflation when a metric, baseline, or evidence path would be more precise.
186
+ - If a paragraph only restates a figure without adding a takeaway or boundary, rewrite it.
187
+
188
+ ### Stop Conditions
189
+
190
+ Do not continue into a full results draft if any of the following is true:
191
+
192
+ - `experiment_res.md` is missing and no equivalent result artifact exists.
193
+ - No figure or table anchor exists for a headline result.
194
+ - A claimed improvement has no explicit baseline.
195
+ - A result claim has no source file or no protocol / guardrail.
196
+ - `paper/figures_manifest.md` is missing for a figure-backed results section.
197
+ - a required figure entry is missing `section`, `placement_hint`, `callout_sentence`, or `supports_claim_ids`
198
+
199
+ 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`.
200
+
201
+ Do not write a results paragraph if:
202
+
203
+ - it cannot be tied to a `claim_id`
204
+ - it has no quantitative statement
205
+ - it makes a comparison without naming a baseline
206
+ - it implicitly depends on a figure but the manifest does not specify the figure contract
207
+
208
+ ### Step 4: Choose the Boundary Surface
209
+
210
+ Do not treat `Limitations` as a default section.
211
+
212
+ Choose the lightest surface that still makes the evidence boundary explicit:
213
+
214
+ - a dedicated `discussion_scope` section
215
+ - a short boundary paragraph in `Conclusion`
216
+ - a short caveat paragraph in `Main Results`
217
+ - a standalone `paper/boundary_notes.md` during drafting
218
+
219
+ Use a dedicated limitations section only when the venue, review criteria, or artifact risk explicitly requires it.
220
+
221
+ If you need a drafting aid, use `references/boundary-notes-template.md`.
222
+
223
+ ### Step 5: Build the PDF
224
+
225
+ Run `bash paper/build_paper.sh`.
226
+
227
+ The build chain should:
228
+
229
+ - write compiler output to `paper/build/build.log`
230
+ - produce `paper/build/manuscript.pdf` when successful
231
+ - write `paper/build/build_errors.md` when the build fails or when `tectonic` is unavailable
232
+
233
+ ### Step 6: Hand Off to the Release Gate
234
+
235
+ Do not treat the manuscript as ready to share immediately after the PDF build succeeds.
236
+
237
+ Before external sharing, run `/artifact-review` so the workspace also has:
238
+
239
+ - `review/artifact_review.md`
240
+ - `review/release_checklist.md`
241
+ - `review/release_gate.json`
242
+
243
+ Treat release readiness as unverified until the release gate is fresh and not `HOLD`.
244
+
245
+ ## Writing Rules
246
+
247
+ 1. No headline metric without baseline + protocol + source path.
248
+ 2. No simulator-only result should be phrased as runtime validation.
249
+ 3. Distinguish observed result from interpretation.
250
+ 4. Keep unsupported ideas in a clearly marked future-work section, not in the main results.
251
+ 5. Do not place a claim in a section that is not listed in its `allowed_in_sections`.
252
+ 6. Do not use empty praise words where a metric, baseline, or scope boundary should appear.
@@ -0,0 +1,34 @@
1
+ # Boundary Notes Template
2
+
3
+ Use this template when a dedicated `Limitations` section is too heavy or too venue-specific.
4
+
5
+ You can surface these notes in any of the following places:
6
+
7
+ - a short `Discussion / Scope Note` section
8
+ - a caveat paragraph at the end of `Main Results`
9
+ - a boundary paragraph in `Conclusion`
10
+ - a standalone drafting file such as `paper/boundary_notes.md`
11
+
12
+ Suggested structure:
13
+
14
+ ```md
15
+ # Boundary Notes
16
+
17
+ ## Supported Today
18
+ - State the strongest supported claim.
19
+
20
+ ## Not Claimed
21
+ - State the stronger claim that is intentionally not made.
22
+
23
+ ## Evidence Boundary
24
+ - Name whether the evidence is simulator, local runtime, or runtime.
25
+
26
+ ## Validation Gaps
27
+ - List the smallest missing validations that prevent stronger wording.
28
+ ```
29
+
30
+ Writing rules:
31
+
32
+ - Keep this concrete and artifact-specific.
33
+ - Prefer a short, sharp boundary note over a generic limitations section.
34
+ - If the manuscript already has a natural home for caveats, fold these points there instead of forcing a dedicated section.
@@ -0,0 +1,32 @@
1
+ # Claim Inventory Template
2
+
3
+ Use this structure for `paper/claim_inventory.md` before drafting any prose:
4
+
5
+ ```yaml
6
+ - claim_id: "claim-001"
7
+ claim_text: "KV2 achieves 17.53% mean TTFT gain vs INT4-FIFO under the stated simulator protocol."
8
+ claim_type: "result"
9
+ source_files:
10
+ - "experiment_res.md"
11
+ - "Comparision-KV2/results/kv2_compare_quant_family_local_20260329.json"
12
+ figure_or_table_anchor: "fig-kv2-tradeoff-overview"
13
+ baseline: "INT4-FIFO"
14
+ protocol_or_guardrail: "quality_penalty_mean <= 0.02"
15
+ evidence_type: "simulator"
16
+ confidence: "high"
17
+ allowed_in_sections:
18
+ - "abstract"
19
+ - "results"
20
+ - "discussion"
21
+ - "conclusion"
22
+ - "boundary_note"
23
+ ```
24
+
25
+ Authoring notes:
26
+
27
+ - Use one claim entry per independently reviewable statement.
28
+ - Use `claim_type=result` for measured outcomes.
29
+ - Use `claim_type=observation` for descriptive trends that stop short of causal interpretation.
30
+ - Use `claim_type=interpretation` for explanation or hypothesis, and keep these out of `abstract` unless independently supported.
31
+ - `allowed_in_sections` is a hard constraint, not a suggestion.
32
+ - If a field is unknown, stop and resolve the evidence gap instead of drafting around it.
@@ -0,0 +1,57 @@
1
+ # Evidence Contract
2
+
3
+ Every headline claim should be recorded using this structure before drafting prose:
4
+
5
+ ```yaml
6
+ - claim_id: "claim-001"
7
+ claim_text: "KV2 achieves 17.53% mean TTFT gain vs INT4-FIFO under the stated simulator protocol."
8
+ claim_type: "result"
9
+ source_files:
10
+ - "Comparision-KV2/results/kv2_compare_quant_family_local_20260329.json"
11
+ - "experiment_res.md"
12
+ figure_or_table_anchor: "fig-kv2-tradeoff-overview"
13
+ baseline: "INT4-FIFO"
14
+ evidence_type: "simulator"
15
+ protocol_or_guardrail: "quality_penalty_mean <= 0.02"
16
+ confidence: "high"
17
+ allowed_in_sections:
18
+ - "abstract"
19
+ - "results"
20
+ - "discussion"
21
+ - "conclusion"
22
+ - "boundary_note"
23
+ ```
24
+
25
+ Required fields:
26
+
27
+ - `claim_id`
28
+ - `claim_text`
29
+ - `claim_type`
30
+ - `source_files`
31
+ - `figure_or_table_anchor`
32
+ - `baseline`
33
+ - `evidence_type`
34
+ - `protocol_or_guardrail`
35
+ - `confidence`
36
+ - `allowed_in_sections`
37
+
38
+ Field notes:
39
+
40
+ - `claim_id` must be stable within the draft and reused by review findings.
41
+ - `claim_type` must be one of `result`, `observation`, or `interpretation`.
42
+ - `source_files` should list every artifact needed to verify the claim.
43
+ - `figure_or_table_anchor` should point to the figure/table label used in the draft or manifest.
44
+ - `confidence` should be `high`, `medium`, or `low`.
45
+ - `allowed_in_sections` defines where the claim may appear in prose. Do not place the claim outside this list.
46
+
47
+ Allowed `evidence_type` values:
48
+
49
+ - `simulator`
50
+ - `local_runtime`
51
+ - `runtime`
52
+
53
+ Minimum writing gate:
54
+
55
+ - Do not draft a headline result if `baseline`, `protocol_or_guardrail`, or `source_files` is missing.
56
+ - Do not place a claim in `abstract` unless `confidence` is `high`.
57
+ - Do not write simulator-only evidence as runtime validation.
@@ -0,0 +1,38 @@
1
+ # Figure Callout Template
2
+
3
+ Use this guide when writing the first prose mention of a figure.
4
+
5
+ The callout sentence should do three jobs:
6
+
7
+ 1. name the figure
8
+ 2. state the concrete takeaway
9
+ 3. name the comparison target or evaluation frame when that is central to the claim
10
+
11
+ Preferred structure:
12
+
13
+ ```text
14
+ Figure \ref{{latex_label}} shows {takeaway_sentence} under {protocol or evaluation frame}.
15
+ ```
16
+
17
+ Examples:
18
+
19
+ ```text
20
+ Figure \ref{fig:kv2-tradeoff-overview} shows that KV2 improves TTFT relative to INT4-FIFO under the shared simulator protocol.
21
+ ```
22
+
23
+ ```text
24
+ Figure \ref{fig:runtime-smoke} shows that the local runtime smoke test preserves the winner ordering observed in the simulator summary.
25
+ ```
26
+
27
+ Avoid callouts that only announce the figure:
28
+
29
+ ```text
30
+ Figure 3 shows the results.
31
+ ```
32
+
33
+ Good callouts should:
34
+
35
+ - appear before the figure block or at the first discussion point
36
+ - contain the main takeaway, not just a pointer
37
+ - stay consistent with `caption_long`
38
+ - avoid introducing a stronger claim than the figure actually supports
@@ -0,0 +1,44 @@
1
+ # Figures Manifest Template
2
+
3
+ Use this structure for `paper/figures_manifest.md`.
4
+
5
+ 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.
6
+
7
+ ```yaml
8
+ - figure_id: "fig-kv2-tradeoff-overview"
9
+ file_path: "paper/figures/kv2_tradeoff_overview.pdf"
10
+ latex_label: "fig:kv2-tradeoff-overview"
11
+ section: "main_results"
12
+ placement_hint: "figure[t]"
13
+ caption_short: "KV2 versus INT4-FIFO and quant-family baselines under the simulator protocol."
14
+ 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."
15
+ takeaway_sentence: "KV2 improves TTFT relative to INT4-FIFO, but the strongest bytes-efficiency challenger remains KVQuant-3bit-1% under the same harness."
16
+ callout_sentence: "Figure \\ref{fig:kv2-tradeoff-overview} compares KV2 with INT4-FIFO and quant-family baselines under the shared simulator protocol."
17
+ baseline: "INT4-FIFO"
18
+ evidence_type: "simulator"
19
+ source_metrics:
20
+ - "mean_ttft_gain_vs_int4_pct"
21
+ - "mean_bytes_gain_vs_int4_pct"
22
+ source_files:
23
+ - "experiment_res.md"
24
+ - "Comparision-KV2/results/kv2_compare_quant_family_local_20260329.md"
25
+ supports_claim_ids:
26
+ - "claim-001"
27
+ - "claim-003"
28
+ must_appear_before_claim_ids:
29
+ - "claim-001"
30
+ ```
31
+
32
+ Rules:
33
+
34
+ - Use one entry per figure, not one entry per paragraph.
35
+ - `section` should name the manuscript module that owns the figure, such as `main_results`, `experimental_protocol`, or `ablations`.
36
+ - `placement_hint` must already be TeX-oriented, for example `figure[t]`, `figure[b]`, `figure* [t]`, or `inline_reference_only`.
37
+ - `caption_short` is for the optional short caption in `\caption[...]`.
38
+ - `caption_long` must include the scientific meaning, the comparison target, and the relevant scope or protocol note when needed.
39
+ - `takeaway_sentence` is the one-sentence interpretation the prose should not forget to make explicit.
40
+ - `callout_sentence` is the first sentence that should introduce the figure in the body text.
41
+ - `supports_claim_ids` lists which claims the figure directly supports.
42
+ - `must_appear_before_claim_ids` lists the claims that should not appear before the reader has seen or been introduced to this figure.
43
+
44
+ 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.
@@ -0,0 +1,22 @@
1
+ # LaTeX Starter Bundle
2
+
3
+ This starter bundle is copied into `paper/` when a new research workspace is created.
4
+
5
+ It provides:
6
+
7
+ - `manuscript.tex` as the top-level entry point
8
+ - `sections/*.tex` for section-by-section drafting
9
+ - `references.bib` as the bibliography placeholder
10
+ - `build_paper.sh` to compile the PDF with `tectonic`
11
+
12
+ Expected outputs after running the build script:
13
+
14
+ - `paper/build/manuscript.pdf`
15
+ - `paper/build/build.log`
16
+ - `paper/build/build_errors.md` when compilation fails
17
+
18
+ Notes:
19
+
20
+ - The default bibliography commands in `manuscript.tex` are commented out to keep the first build path simple.
21
+ - Uncomment the bibliography lines after citations and BibTeX entries are ready.
22
+ - 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.
@@ -0,0 +1,41 @@
1
+ #!/usr/bin/env bash
2
+ set -euo pipefail
3
+
4
+ PAPER_DIR="$(cd "$(dirname "$0")" && pwd)"
5
+ BUILD_DIR="$PAPER_DIR/build"
6
+ LOG_PATH="$BUILD_DIR/build.log"
7
+ ERROR_PATH="$BUILD_DIR/build_errors.md"
8
+
9
+ mkdir -p "$BUILD_DIR"
10
+
11
+ if ! command -v tectonic >/dev/null 2>&1; then
12
+ cat >"$ERROR_PATH" <<'EOF'
13
+ # Paper Build Error
14
+
15
+ `tectonic` was not found in `PATH`.
16
+
17
+ Install `tectonic` first, then rerun:
18
+
19
+ ```bash
20
+ bash paper/build_paper.sh
21
+ ```
22
+ EOF
23
+ exit 1
24
+ fi
25
+
26
+ cd "$PAPER_DIR"
27
+
28
+ if tectonic --outdir "$BUILD_DIR" manuscript.tex >"$LOG_PATH" 2>&1; then
29
+ rm -f "$ERROR_PATH"
30
+ else
31
+ {
32
+ echo "# Paper Build Error"
33
+ echo
34
+ echo "The LaTeX build failed. See \`paper/build/build.log\` for the full compiler output."
35
+ echo
36
+ echo '```text'
37
+ tail -n 80 "$LOG_PATH" || true
38
+ echo '```'
39
+ } >"$ERROR_PATH"
40
+ exit 1
41
+ fi
@@ -0,0 +1,39 @@
1
+ \documentclass[11pt]{article}
2
+
3
+ \usepackage[margin=1in]{geometry}
4
+ \usepackage[T1]{fontenc}
5
+ \usepackage[utf8]{inputenc}
6
+ \usepackage{microtype}
7
+ \usepackage{amsmath,amssymb}
8
+ \usepackage{booktabs}
9
+ \usepackage{graphicx}
10
+ \usepackage{xcolor}
11
+ \usepackage{hyperref}
12
+
13
+ \title{Paper Title Placeholder}
14
+ \author{Author Placeholder}
15
+ \date{}
16
+
17
+ \begin{document}
18
+
19
+ \maketitle
20
+
21
+ \input{sections/abstract}
22
+ \input{sections/introduction}
23
+ \input{sections/problem_setup}
24
+ \input{sections/method_system}
25
+ \input{sections/experimental_protocol}
26
+ \input{sections/main_results}
27
+
28
+ % Optional modules: enable only if the current paper shape needs them.
29
+ % \input{sections/related_work}
30
+ % \input{sections/ablations}
31
+ % \input{sections/discussion_scope}
32
+
33
+ \input{sections/conclusion}
34
+
35
+ % Uncomment after citations and BibTeX entries are ready.
36
+ % \bibliographystyle{plain}
37
+ % \bibliography{references}
38
+
39
+ \end{document}
@@ -0,0 +1,10 @@
1
+ % Add BibTeX entries here.
2
+ %
3
+ % Example:
4
+ %
5
+ % @article{example2026,
6
+ % title={Example Title},
7
+ % author={Example, A. and Example, B.},
8
+ % journal={arXiv preprint arXiv:2601.00001},
9
+ % year={2026}
10
+ % }
@@ -0,0 +1,3 @@
1
+ \section{Ablations and Additional Analysis}
2
+
3
+ Add ablations, sensitivity analysis, or secondary result slices here. Keep them clearly separated from headline results.
@@ -0,0 +1,3 @@
1
+ \begin{abstract}
2
+ State the problem, the proposed method or system, one supported quantitative result, and the scope boundary. Keep every claim aligned with `claim_inventory.md`.
3
+ \end{abstract}
@@ -0,0 +1,3 @@
1
+ \section{Conclusion}
2
+
3
+ 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.
@@ -0,0 +1,7 @@
1
+ \section{Discussion / Scope Note}
2
+
3
+ % Use this optional module only when the paper benefits from a dedicated
4
+ % place to separate observation from interpretation or to state the evidence
5
+ % boundary explicitly. Do not enable it by default.
6
+
7
+ Separate observed results from interpretation, and make the current evidence boundary explicit only if this paper shape needs a dedicated scope note.