scientify 3.0.0 → 3.2.0

package/skills/figure-standardize/references/figure-placement-template.md

@@ -0,0 +1,30 @@
+# Figure Placement Template
+
+Use this guide when assigning `section` and `placement_hint` in `paper/figures_manifest.md`.
+
+Recommended fields:
+
+```yaml
+section: "main_results"
+placement_hint: "figure[t]"
+must_appear_before_claim_ids:
+  - "claim-001"
+```
+
+Placement hint options:
+
+- `figure[t]`
+  - standard single-column top placement
+- `figure[b]`
+  - standard single-column bottom placement
+- `figure* [t]`
+  - wide figure for two-column layouts
+- `inline_reference_only`
+  - no figure block in the current section; the text only points to a figure placed elsewhere
+
+Placement rules:
+
+- Put the figure in the same section that carries its main supported claim whenever possible.
+- If a figure supports a headline result, the first callout should appear before or immediately adjacent to the corresponding claim.
+- Do not place a figure so late that the reader sees the claim well before the figure is introduced.
+- Use `must_appear_before_claim_ids` to mark claims that should not appear before the figure callout.

package/skills/figure-standardize/references/figure-style-guide.md

@@ -0,0 +1,36 @@
+# Figure Style Guide
+
+Use one consistent style across a figure family:
+
+- one font family
+- one semantic color per method family
+- one stable baseline line style
+- explicit units in axis labels
+- compact legend names
+- protocol note under the figure or in the caption
+- one stable caption and callout structure across the family
+
+Required paper-facing figure contract fields:
+
+- `caption_short`
+- `caption_long`
+- `callout_sentence`
+- `placement_hint`
+- `supports_claim_ids`
+
+Required caption fields:
+
+- what is compared
+- which baseline is used
+- what metric is shown
+- what evidence type supports the figure
+- what protocol or guardrail defines the evaluation regime when that matters for the claim
+
+Paper-facing figures should stay aligned across four surfaces:
+
+1. `paper/figures_manifest.md`
+2. the first prose callout
+3. the figure caption
+4. the eventual LaTeX figure block
+
+Do not let these four surfaces drift apart.

package/skills/release-layout/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: release-layout
+description: "Use this when the user wants to improve README, docs pages, or microsites so a new reader can understand what the project is, how to use it, what artifacts exist, and what the scope boundaries are within one screen."
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🪄",
+      },
+  }
+---
+
+# Release Layout
+
+**Don't ask permission. Just do it.**
+
+Use this skill for outward-facing packaging surfaces such as:
+
+- `README.md`
+- `docs/index.html`
+- release page generator scripts
+
+This skill improves structure and legibility. It does **not** upgrade the scientific claim on its own.
+
+## Core Goal
+
+A first-time reader should understand, within one screen:
+
+1. what this is
+2. how to use it
+3. what artifacts it produces
+4. what the scope boundary is
+
+## Workflow
+
+### Step 1: Detect the Real Edit Target
+
+If a page is generated by a script, prefer editing the generator rather than the built HTML.
+
+If `review/release_gate.json` exists, read it before polishing release-facing copy.
+
+### Step 2: Audit the First Screen
+
+Check whether the hero / opening section answers the four core questions above.
+
+### Step 3: Reshape the Page
+
+Prefer this order:
+
+1. hero / product definition
+2. quick-start or usage path
+3. artifact map
+4. evidence / results block
+5. scope note
+6. FAQ or next steps
+
+Use `references/page-structure.md`.
+
+### Step 4: Clean the Reading Path
+
+Reduce:
+
+- duplicated claims
+- buried usage instructions
+- unexplained metrics
+- isolated figures without framing text
+
+## Safety Rules
+
+1. Do not hide limitations for the sake of visual polish.
+2. Do not introduce stronger language than the underlying artifacts support.
+3. If the result is simulator-only, say that near the top instead of burying it below the fold.
+4. If the release gate is `HOLD`, stale, or missing for a share-ready artifact set, do not present the project as fully ready to share.

package/skills/release-layout/references/page-structure.md

@@ -0,0 +1,14 @@
+# Page Structure
+
+Recommended first-screen order:
+
+1. one-line definition
+2. quick-start
+3. artifact outputs
+4. evidence boundary
+
+Avoid:
+
+- leading with large result claims before the project is defined
+- hiding usage instructions below the fold
+- showing figures without telling the reader what they mean

package/skills/research-experiment/SKILL.md

@@ -30,7 +30,7 @@ metadata:
 
 | File | Content |
 |------|---------|
-| `experiment_res.md` | 完整实验报告（含 full training + 消融 + 补充实验） |
+| `experiment_res.md` | Full experiment report (full training, ablations, supplementary experiments) with explicit headline metrics, baselines, guardrails, and figure anchors |
 | `experiment_analysis/analysis_{N}.md` | 每轮实验分析报告（迭代过程中产生） |
 
 ---
@@ -128,6 +128,9 @@ python3 run.py --experiment {exp_name}
 - [RESULT] val_metric={value}
 - [RESULT] elapsed={value}
 - [RESULT] device={device}
+- [METRIC] name={headline_metric} value={value} unit={unit} baseline={baseline}
+- [GUARD] name={guard_name} value={value} threshold={threshold} pass={true/false}
+- [FIGURE] file={figure path}
 
 > 以上数值来自真实执行输出。
 
@@ -156,6 +159,11 @@ python3 run.py --experiment {exp_name}
 | Ours | {value} | — |
 | {Baseline} | {value} | ... |
 
+## Scope / Evidence Boundary
+- baseline: {which baseline is used}
+- protocol / guardrail: {evaluation rule}
+- evidence_type: {simulator / local_runtime / full_runtime}
+
 ### Visualizations
 - 训练曲线: `project/figures/training_curve.png`
 - {其他可视化}: `project/figures/{name}.png`
@@ -177,3 +185,4 @@ python3 run.py --experiment {exp_name}
 4. 如果 full training 失败（OOM 等），调整 batch_size 后重试，不要跳过
 5. **补充实验迭代必须做 2 轮（Novix Exp Analyzer 机制）** — 第 1 轮针对初始结果，第 2 轮针对补充实验结果
 6. 补充实验不改核心算法，只改实验配置/参数/可视化代码
+7. Every headline metric must include a baseline, and every main conclusion must point back to real outputs or figure files

package/skills/research-survey/SKILL.md

@@ -28,8 +28,8 @@ Read and verify these files exist before starting:
 
 | File | Content |
 |------|---------|
-| `knowledge/paper_{id}.md` | Per-paper structured notes |
-| `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 |
 
 ---
 
@@ -79,6 +79,15 @@ ls papers/
 写入 `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}
@@ -121,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}
+
 ## 技术路线建议
 
 基于以上分析，推荐的技术路线是：
@@ -151,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