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.
- package/README.en.md +21 -1
- package/README.md +27 -0
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- package/dist/src/cli/research.d.ts.map +1 -1
- package/dist/src/cli/research.js +42 -1
- package/dist/src/cli/research.js.map +1 -1
- package/dist/src/commands.d.ts.map +1 -1
- package/dist/src/commands.js +159 -1
- package/dist/src/commands.js.map +1 -1
- package/dist/src/release-gate.d.ts +14 -0
- package/dist/src/release-gate.d.ts.map +1 -0
- package/dist/src/release-gate.js +124 -0
- package/dist/src/release-gate.js.map +1 -0
- package/dist/src/templates/bootstrap.d.ts.map +1 -1
- package/dist/src/templates/bootstrap.js +139 -62
- package/dist/src/templates/bootstrap.js.map +1 -1
- package/openclaw.plugin.json +8 -1
- package/package.json +1 -1
- package/skills/algorithm-selection/SKILL.md +103 -0
- package/skills/algorithm-selection/references/candidate-template.md +13 -0
- package/skills/algorithm-selection/references/selection-template.md +39 -0
- package/skills/artifact-review/SKILL.md +146 -0
- package/skills/artifact-review/references/release-gate-template.md +40 -0
- package/skills/artifact-review/references/review-checklist.md +45 -0
- package/skills/artifact-review/references/style-review-checklist.md +30 -0
- package/skills/baseline-runner/SKILL.md +103 -0
- package/skills/baseline-runner/references/baseline-matrix-template.md +9 -0
- package/skills/baseline-runner/references/baseline-report-template.md +25 -0
- package/skills/dataset-validate/SKILL.md +104 -0
- package/skills/dataset-validate/references/data-validation-template.md +38 -0
- package/skills/figure-standardize/SKILL.md +110 -0
- package/skills/figure-standardize/references/caption-template.md +12 -0
- package/skills/figure-standardize/references/figure-placement-template.md +30 -0
- package/skills/figure-standardize/references/figure-style-guide.md +36 -0
- package/skills/release-layout/SKILL.md +73 -0
- package/skills/release-layout/references/page-structure.md +14 -0
- package/skills/research-experiment/SKILL.md +10 -1
- package/skills/research-survey/SKILL.md +19 -2
- package/skills/write-paper/SKILL.md +252 -0
- package/skills/write-paper/references/boundary-notes-template.md +34 -0
- package/skills/write-paper/references/claim-inventory-template.md +32 -0
- package/skills/write-paper/references/evidence-contract.md +57 -0
- package/skills/write-paper/references/figure-callout-template.md +38 -0
- package/skills/write-paper/references/figures-manifest-template.md +44 -0
- package/skills/write-paper/references/latex/README.md +22 -0
- package/skills/write-paper/references/latex/build_paper.sh +41 -0
- package/skills/write-paper/references/latex/manuscript.tex +39 -0
- package/skills/write-paper/references/latex/references.bib +10 -0
- package/skills/write-paper/references/latex/sections/ablations.tex +3 -0
- package/skills/write-paper/references/latex/sections/abstract.tex +3 -0
- package/skills/write-paper/references/latex/sections/conclusion.tex +3 -0
- package/skills/write-paper/references/latex/sections/discussion_scope.tex +7 -0
- package/skills/write-paper/references/latex/sections/experimental_protocol.tex +3 -0
- package/skills/write-paper/references/latex/sections/introduction.tex +3 -0
- package/skills/write-paper/references/latex/sections/main_results.tex +9 -0
- package/skills/write-paper/references/latex/sections/method_system.tex +3 -0
- package/skills/write-paper/references/latex/sections/problem_setup.tex +3 -0
- package/skills/write-paper/references/latex/sections/related_work.tex +3 -0
- package/skills/write-paper/references/paper-template.md +155 -0
- package/skills/write-paper/references/paragraph-contract.md +139 -0
- package/skills/write-paper/references/paragraph-examples.md +171 -0
- package/skills/write-paper/references/style-banlist.md +81 -0
- 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` |
|
|
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,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.
|